# Affiliate Postback URLs
Source: https://docs.elasticfunnels.io/affiliates/postback-urls

Send signed JSON postbacks to your affiliates' endpoints on commission-relevant lifecycle events.

ElasticFunnels can POST a small, **standardized JSON payload** to a URL on your
affiliate's side every time a commission-relevant event happens — independent of
which gateway processed the order.

This is the *outbound* side of affiliate tracking. The payload is intentionally
**lean**: it contains only what an affiliate needs to reconcile a conversion in
their own system. **Customer details, billing addresses, and product line items
are deliberately excluded.**

If you need rich gateway-aware payloads (with customer info, products, etc.) for
your *own* systems, use the [Merchant Postback URLs](/merchants/postback-urls)
instead.

## How it differs from the legacy macro postback

Affiliates have an existing single-URL **GET** mechanism with macros like
`{subid}`, `{amount}`, `{txn_id}` — that one is unchanged and still works.

The system documented here is **additive**:

| | Legacy `postback_url` | Outbound Postback URLs (this page) |
| - | - | - |
| Method | `GET` with query macros | `POST` with JSON body |
| URLs | One per affiliate | One per **event** |
| Auth | None | HMAC `X-EF-Signature` (+ optional Bearer token) |
| Retries | Best-effort, no log | Queued + exponential backoff + delivery log |
| Events | Purchase only | Purchase, refund, chargeback, renewal, cancel |
| Affiliate types | `affcenter` only | All affiliate types |

You can use either, both, or neither.

## Configuration

In **Affiliates → Edit affiliate → Postback URLs** you'll find:

1. **HMAC Signing Secret** — auto-generated per affiliate. Used to verify each
   request. Keep it secret. You can rotate it at any time; old endpoints will
   start failing signature checks until they pick up the new secret.
2. **Per-event Postback URLs** — one row per supported event. Each row has:
   * `URL` — `https://example.com/webhooks/affiliate-purchase`
   * `Bearer Token (optional)` — sent as `Authorization: Bearer …` if set
   * `Enabled` — toggle without losing the URL
3. **Send test** — fires a synthetic payload (with `"test": true`) for that event.
4. **Recent Deliveries** — log of every attempt with HTTP status, payload, response
   body, and a manual retry button.

## Supported events

| Event key | When it fires |
| - | - |
| `purchase` | A purchase conversion is approved for this affiliate. |
| `refund` | An order or order line is refunded. |
| `chargeback` | A chargeback is recorded against the order. |
| `subscription_renewal` | A recurring subscription is successfully billed. |
| `subscription_renewal_failed` | A recurring billing attempt fails. |
| `subscription_cancel` | The subscription is cancelled or stopped. |

Affiliate postbacks intentionally do **not** include `shipped`, `abandon`, or
`failed_payment` — those aren't commission-bearing events.

## Request format

### HTTP

```
POST https://your-endpoint.example.com/webhooks/affiliate-purchase
Content-Type: application/json
User-Agent: ElasticFunnels-AffiliatePostback/1.0
X-EF-Event: purchase
X-EF-Delivery-Id: 01HXYZ...
X-EF-Timestamp: 1735689600
X-EF-Signature: sha256=<hex hmac>
X-EF-Brand-Id: 42
X-EF-Affiliate-Id: 123
Authorization: Bearer <optional-token-if-configured>
```

### Signature verification

The signature is `HMAC_SHA256(secret, "<X-EF-Timestamp>.<raw_body>")`, hex-encoded
and prefixed with `sha256=`.

Always verify both the signature **and** the timestamp (reject anything older
than \~5 minutes to defeat replays).

<CodeGroup>
  ```php PHP theme={null}
  $secret = getenv('EF_AFFILIATE_POSTBACK_SECRET');
  $payload = file_get_contents('php://input');
  $timestamp = $_SERVER['HTTP_X_EF_TIMESTAMP'] ?? '';
  $received = $_SERVER['HTTP_X_EF_SIGNATURE'] ?? '';

  if (abs(time() - (int)$timestamp) > 300) {
      http_response_code(400);
      exit('Timestamp too old');
  }

  $expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $payload, $secret);

  if (!hash_equals($expected, $received)) {
      http_response_code(401);
      exit('Bad signature');
  }

  $event = json_decode($payload, true);
  // process $event...
  http_response_code(200);
  echo 'ok';
  ```

  ```javascript Node.js (Express) theme={null}
  import crypto from 'node:crypto';

  app.post('/webhooks/affiliate', express.raw({ type: 'application/json' }), (req, res) => {
    const secret = process.env.EF_AFFILIATE_POSTBACK_SECRET;
    const ts = req.get('X-EF-Timestamp') || '';
    const sig = req.get('X-EF-Signature') || '';

    if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
      return res.status(400).send('Timestamp too old');
    }

    const expected = 'sha256=' + crypto
      .createHmac('sha256', secret)
      .update(`${ts}.${req.body.toString()}`)
      .digest('hex');

    if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) {
      return res.status(401).send('Bad signature');
    }

    const event = JSON.parse(req.body.toString());
    // process event...
    res.sendStatus(200);
  });
  ```

  ```python Python theme={null}
  import hmac, hashlib, time, json
  from flask import Flask, request, abort

  SECRET = os.environ['EF_AFFILIATE_POSTBACK_SECRET'].encode()

  @app.post('/webhooks/affiliate')
  def webhook():
      body = request.get_data()
      ts = request.headers.get('X-EF-Timestamp', '')
      sig = request.headers.get('X-EF-Signature', '')

      if abs(time.time() - int(ts)) > 300:
          abort(400, 'Timestamp too old')

      expected = 'sha256=' + hmac.new(SECRET, f'{ts}.'.encode() + body, hashlib.sha256).hexdigest()
      if not hmac.compare_digest(expected, sig):
          abort(401, 'Bad signature')

      event = json.loads(body)
      # process event...
      return '', 200
  ```
</CodeGroup>

## Response handling

Return any **2xx** response to acknowledge delivery. Anything else (timeouts,
non-2xx, network errors) is recorded as a failure and retried with exponential
backoff at **1m, 5m, 30m, 2h, 12h** (5 attempts total) before being marked
`dead`. Dead deliveries can be manually retried from the Recent Deliveries log.

## Payload schema

Every event uses the same envelope. Numeric amounts may be **negative** for
clawback events (`refund`, `chargeback`, `subscription_renewal_failed`).

```json theme={null}
{
  "event": "purchase",
  "event_id": "ef_aff_evt_01HXYZABC...",
  "occurred_at": "2026-04-18T15:32:01+00:00",
  "test": false,
  "brand_id": 42,

  "affiliate": {
    "id": 123,
    "type": "affcenter",
    "merchant_account_id": 8801,
    "default_subid": "spring_promo"
  },

  "offer": {
    "funnel_id": 17,
    "funnel_code": "vip-funnel",
    "name": "VIP Funnel"
  },

  "amount": 49.00,
  "currency": "USD",
  "commission": 12.00,

  "transaction": {
    "order_id": "GW-ORDER-1001",
    "public_order_id": "EF-1001",
    "transaction_id": "ch_3PXyz",
    "conversion_code": "cv_01HXYZ...",
    "original_conversion_code": null,
    "type": "purchase",
    "status": "approved",
    "is_subscription": false
  },

  "tracking": {
    "click_code": "ck_AbCdEf",
    "session_id": "sess_01HXY...",
    "subid": "campaign_a",
    "subid2": "creative_1",
    "subid3": null,
    "subid4": null,
    "subid5": null,
    "utm_source": "facebook",
    "utm_medium": "paid",
    "utm_campaign": "spring_2026",
    "utm_term": null,
    "utm_content": "ad_set_3",
    "gclid": null,
    "fbclid": "fb.1.1700000000.AbCdEf",
    "vtid": null
  }
}
```

### Field reference

| Field | Notes |
| - | - |
| `event` | One of the supported event keys above. |
| `event_id` | Unique, prefixed `ef_aff_evt_…`. Use it to dedupe on your side. |
| `occurred_at` | ISO-8601, server time of the underlying conversion event. |
| `test` | `true` for "Send test" payloads, `false` for live events. |
| `affiliate.*` | Identifies the affiliate the conversion is attributed to. |
| `offer.name` | The funnel title — typically what you see as your "offer name". |
| `offer.funnel_code` | Stable, URL-safe slug of the funnel. |
| `amount` | Order amount in the currency below. Negative for clawbacks. |
| `commission` | The affiliate's calculated commission for this event. |
| `transaction.transaction_id` | Gateway transaction id when available. |
| `transaction.conversion_code` | ElasticFunnels conversion identifier. |
| `transaction.original_conversion_code` | For refunds/chargebacks: the original purchase's conversion code. |
| `tracking.subid` … `subid5` | Affiliate-defined subids captured from the click. |
| `tracking.click_code` | EF's click identifier; correlate with your own click logs. |

### What's deliberately **not** in the payload

* Customer name, email, phone, address, IP — affiliates don't need PII to reconcile.
* Product-level details (SKUs, line items, shipping/billing).
* Anything specific to the underlying gateway.

If you need that data for your own systems, use the
[Merchant Postback URLs](/merchants/postback-urls) — those are signed by the
merchant secret and contain the full conversion record.

## Operational details

* Deliveries are processed asynchronously.
* Failed deliveries are retried automatically after their backoff window has elapsed.
* The Recent Deliveries section in the affiliate form shows delivery attempts and outcomes.
* Rotating the signing secret immediately invalidates the old one. Coordinate
  the change with your affiliate before rotating in production.

## Testing locally

Point a URL at [webhook.site](https://webhook.site) or `ngrok`, hit **Send
test** for the event you want, and you'll see the payload + headers arrive
within seconds.


# Ad Spend Metrics
Source: https://docs.elasticfunnels.io/analytics/ad-spend-metrics

Track advertising performance, costs, and return on investment across all your marketing campaigns

## At a glance

**Quick Summary**: Ad spend metrics help you measure the effectiveness and profitability of your advertising campaigns. These metrics show how much you're spending, what you're getting in return, and where to optimize your budget.

**Most Important**: Return on Ad Spend (ROAS), Cost Per Acquisition (CPA), and Cost Per Click (CPC) are your core advertising performance indicators.

**Bottom Line**: Profitable advertising requires ROAS above 3:1 minimum, with 4:1+ being good performance. Monitor these metrics to optimize budget allocation and campaign performance.

***

## Core Ad Spend Metrics

### Return on Ad Spend (ROAS)

**What it is**: Revenue generated for every dollar spent on advertising

**How it's calculated**: Revenue ÷ Ad Spend

**Example**: $5,000 revenue from $1,000 ad spend = 5:1 ROAS

**Why it's crucial**:

* Shows direct profitability of ad campaigns
* Helps determine budget allocation
* Compares performance across different channels
* Guides scaling decisions

**Benchmarks**:

* 3:1 ROAS: Break-even point (minimum)
* 4:1 ROAS: Good performance
* 6:1+ ROAS: Excellent performance
* 8:1+ ROAS: Outstanding performance

**Industry variations**:

* E-commerce: 4:1 - 6:1 typical
* SaaS: 3:1 - 5:1 typical
* High-ticket items: 2:1 - 4:1 acceptable
* Low-margin products: 6:1+ needed

***

### Cost Per Acquisition (CPA)

**What it is**: How much you pay to acquire one customer through advertising

**How it's calculated**: Total Ad Spend ÷ Number of Customers Acquired

**Example**: $1,000 ad spend, 50 new customers = $20 CPA

**Why it matters**:

* Must be significantly less than customer lifetime value
* Shows efficiency of your acquisition funnel
* Helps set profitable bid limits
* Guides budget allocation decisions

**Target guidelines**:

* CPA should be 1/3 to 1/5 of customer lifetime value
* Lower CPA allows for more aggressive scaling
* Track CPA trends over time for optimization

**Ways to improve**:

* Improve landing page conversion rates
* Refine audience targeting
* Test different ad creatives
* Optimize bidding strategies

***

### Cost Per Click (CPC)

**What it is**: Average amount you pay for each click on your ads

**How it's calculated**: Total Ad Spend ÷ Total Clicks

**Example**: $500 ad spend, 1,000 clicks = $0.50 CPC

**Why it's important**:

* Shows competitiveness of your market
* Indicates ad relevance and quality
* Helps forecast campaign costs
* Compares efficiency across campaigns

**Factors affecting CPC**:

* Industry competition
* Ad quality and relevance
* Targeting specificity
* Bidding strategy
* Time of day/seasonality

**Optimization tactics**:

* Improve ad quality scores
* Use negative keywords
* Refine audience targeting
* Test different bidding strategies
* Optimize ad scheduling

***

## Advanced Ad Spend Metrics

### Customer Acquisition Cost (CAC)

**What it is**: Total cost to acquire one customer (includes all marketing expenses)

**How it's calculated**: Total Marketing Spend ÷ Number of New Customers

**Example**: $2,000 total marketing spend, 100 new customers = $20 CAC

**Difference from CPA**: CAC includes all marketing costs, not just paid ads

**What it includes**:

* Includes organic marketing efforts
* Shows true cost of customer acquisition
* Better for long-term planning
* More accurate for ROI calculations

**Components included**:

* Paid advertising spend
* Content creation costs
* Marketing team salaries
* Marketing tools and software
* Agency fees

***

### Click-Through Rate (CTR)

**What it is**: Percentage of people who click your ads after seeing them

**How it's calculated**: (Clicks ÷ Impressions) × 100

**Example**: 1,000 clicks from 50,000 impressions = 2% CTR

**Why it matters**:

* Shows ad relevance and appeal
* Affects ad platform quality scores
* Influences CPC and ad delivery
* Indicates audience targeting accuracy

**Good benchmarks by platform**:

* Google Ads: 2-3% average
* Facebook Ads: 1-2% average
* LinkedIn Ads: 0.4-0.6% average
* Display ads: 0.5-1% average

**Improvement strategies**:

* Test compelling headlines
* Use strong call-to-actions
* Improve visual elements
* Refine audience targeting
* A/B test ad copy variations

***

### Cost Per Thousand Impressions (CPM)

**What it is**: Cost to show your ad to 1,000 people

**How it's calculated**: (Ad Spend ÷ Impressions) × 1,000

**Example**: $100 spend for 50,000 impressions = $2 CPM

**When to focus on CPM**:

* Brand awareness campaigns
* Broad reach objectives
* Video view campaigns
* Top-of-funnel marketing

**Factors affecting CPM**:

* Audience size and competition
* Ad placement and format
* Seasonality and timing
* Geographic targeting
* Industry and niche

***

## Platform-Specific Metrics

### Google Ads Metrics

**Quality Score**:

* Measures ad relevance and landing page experience
* Affects CPC and ad positioning
* Scale of 1-10 (higher is better)
* Improves with better CTR and relevance

**Search Impression Share**:

* Percentage of available impressions your ads received
* Shows potential for increased visibility
* Lost impression share indicates missed opportunities

**Average Position** (Legacy):

* Historical metric showing ad placement
* Replaced by impression share metrics
* Still useful for understanding competition

***

### Facebook/Meta Ads Metrics

**Cost Per Result**:

* Platform-specific cost per desired action
* Varies by campaign objective
* More relevant than generic CPC for optimization

**Frequency**:

* Average number of times each person saw your ad
* High frequency can lead to ad fatigue
* Optimal range: 1.5-3 for most campaigns

**Relevance Score** (Legacy):

* Replaced by quality ranking, engagement rate ranking, and conversion rate ranking
* Indicates ad performance relative to competition

***

### LinkedIn Ads Metrics

**Social Actions**:

* Likes, comments, shares on your ads
* Indicates engagement and content quality
* Can improve organic reach

**Demographic Performance**:

* Detailed breakdowns by job title, company size, industry
* Helps refine B2B targeting
* Shows which segments perform best

***

## Budget Management Metrics

### Daily Budget Utilization

**What it is**: Percentage of daily budget actually spent

**How to calculate**: (Actual Daily Spend ÷ Daily Budget) × 100

**Why it matters**:

* Shows if budgets are constraining performance
* Indicates bid competitiveness
* Helps identify scaling opportunities

**Optimization actions**:

* Increase budgets for underutilized high-performers
* Adjust bids for better budget utilization
* Expand targeting for more volume

***

### Budget Allocation Efficiency

**What it is**: How effectively budget is distributed across campaigns

**Key considerations**:

* Allocate more budget to high-ROAS campaigns
* Reduce spend on underperforming segments
* Test budget increases on promising campaigns
* Maintain minimum budgets for statistical significance

***

### Lifetime Budget Pacing

**What it is**: Rate at which lifetime budgets are being consumed

**Why it's important**:

* Prevents budget exhaustion too early
* Ensures consistent ad delivery
* Helps plan campaign duration

***

## Attribution and Tracking

### Attribution Models

**First-Click Attribution**:

* Credits first touchpoint with conversion
* Good for understanding awareness drivers
* May undervalue nurturing touchpoints

**Last-Click Attribution**:

* Credits final touchpoint before conversion
* Simple but may miss influence of earlier ads
* Default in many platforms

**Multi-Touch Attribution**:

* Distributes credit across multiple touchpoints
* More accurate for complex customer journeys
* Requires advanced tracking setup

***

### Conversion Tracking Setup

**Essential tracking**:

* Purchase/conversion events
* Conversion values
* Cross-device tracking
* Offline conversion imports

**Advanced tracking**:

* View-through conversions
* Assisted conversions
* Customer lifetime value
* Return customer identification

***

## Optimization Strategies

### Campaign-Level Optimization

**Budget reallocation**:

* Move budget from low-ROAS to high-ROAS campaigns
* Pause underperforming campaigns
* Scale successful campaigns gradually
* Test new campaign types

**Bidding optimization**:

* Use automated bidding for efficiency
* Set appropriate target ROAS/CPA
* Adjust bids based on performance data
* Consider dayparting for better timing

***

### Ad Group/Ad Set Optimization

**Audience refinement**:

* Exclude converting audiences from prospecting
* Create lookalike audiences from best customers
* Use negative audiences to reduce waste
* Test audience expansion options

**Creative optimization**:

* Rotate ad creatives regularly
* Test different value propositions
* Use dynamic creative optimization
* Analyze creative performance data

***

### Keyword and Targeting Optimization

**Search campaigns**:

* Add negative keywords regularly
* Expand successful keyword themes
* Adjust match types based on performance
* Use search term reports for insights

**Display and social campaigns**:

* Exclude poor-performing placements
* Refine demographic targeting
* Test interest and behavior targeting
* Use custom audiences effectively

***

## Reporting and Analysis

### Daily Monitoring

**Key metrics to check**:

* Spend vs. budget
* ROAS performance
* CPA trends
* Major campaign changes

**Alert thresholds**:

* ROAS drops below target
* CPA exceeds acceptable limits
* Budget utilization issues
* Significant traffic changes

***

### Weekly Analysis

**Performance reviews**:

* Campaign performance comparison
* Audience segment analysis
* Creative performance evaluation
* Competitive landscape changes

**Optimization planning**:

* Identify scaling opportunities
* Plan creative refreshes
* Budget reallocation decisions
* New campaign testing

***

### Monthly Strategic Review

**Detailed analysis**:

* Overall account performance
* Customer acquisition trends
* Lifetime value correlation
* Market condition impacts

**Strategic planning**:

* Budget planning for next month
* New platform testing
* Campaign structure optimization
* Long-term growth strategies

***

## Common Issues and Solutions

### High CPA Problems

**Possible causes**:

* Poor landing page conversion
* Broad or irrelevant targeting
* Weak ad creative
* High competition

**Solutions**:

* Optimize landing pages
* Refine audience targeting
* Test new ad creatives
* Adjust bidding strategy

***

### Low ROAS Issues

**Possible causes**:

* Targeting wrong audience
* Poor product-market fit
* Inefficient funnel
* Attribution problems

**Solutions**:

* Analyze customer data
* Test different audiences
* Optimize conversion funnel
* Review attribution settings

***

### Budget Waste

**Common causes**:

* Broad targeting
* Poor negative keyword lists
* Irrelevant placements
* Outdated campaigns

**Prevention strategies**:

* Regular account audits
* Automated rules and alerts
* Performance monitoring
* Continuous optimization

***

## Getting More Help

For assistance with:

* Campaign setup and optimization
* Attribution modeling
* Advanced tracking implementation
* Performance analysis and reporting

Contact our support team or explore our detailed advertising optimization guides.


# Conversion Metrics
Source: https://docs.elasticfunnels.io/analytics/conversions

Understand key conversion metrics like conversion rate, AOV, EPC, and how to optimize your funnel performance

## At a glance

**Quick Summary**: Conversion metrics measure how well your funnels turn visitors into customers and revenue. Key metrics include conversion rate, average order value (AOV), earnings per click (EPC), and customer lifetime value.

**Most Important**: Conversion Rate (% of visitors who buy), AOV (average purchase amount), and EPC (revenue per visitor) are your core performance indicators.

**Bottom Line**: Higher conversion rates and AOV mean more revenue from the same traffic. Focus on these metrics to optimize your funnel performance.

**Related Guides**: For advertising metrics, see [Ad Spend Metrics](/analytics/ad-spend-metrics). For video engagement, see [Video Metrics](/analytics/video-metrics). For detailed user behavior tracking, see [Tracking Metrics](/analytics/tracking-metrics).

***

## Core Conversion Metrics

### Conversion Rate

**What it is**: The percentage of visitors who complete a purchase

**How it's calculated**: (Number of customers ÷ Number of visitors) × 100

**Example**: 1,000 visitors, 50 purchases = 5% conversion rate

**Why it matters**:

* Your most important metric for funnel performance
* Small improvements have big revenue impact
* Industry average is typically 1-3% for e-commerce

**Good benchmarks**:

* 1-2%: Needs improvement
* 3-5%: Good performance
* 5%+: Excellent performance

***

### Sessions vs Customers

**Sessions**: Total number of website visits (including repeat visitors)

**Customers**: Unique individuals who made a purchase

**Why both matter**: Sessions show traffic volume, customers show actual buyers. The ratio between them is your conversion rate.

***

### Average Order Value (AOV)

**What it is**: The average amount customers spend per purchase

**How it's calculated**: Total revenue ÷ Number of orders

**Example**: $10,000 revenue from 100 orders = $100 AOV

**Why it matters**:

* Directly impacts revenue without needing more traffic
* Easier to increase than conversion rate
* Shows effectiveness of upsells and cross-sells

**Ways to improve**:

* Add upsells and cross-sells
* Bundle products together
* Offer volume discounts
* Increase product prices strategically

## Revenue Metrics

### Gross Revenue

**What it is**: Total sales amount before any deductions

**Includes**: All product sales, shipping, taxes, and fees

**Use for**: Understanding total business volume

***

### Net Revenue

**What it is**: Revenue after deductions like refunds, chargebacks, and fees

**More accurate for**: Actual money you keep from sales

**Why it's important**: Shows true business performance after costs

***

### Earnings Per Click (EPC)

**What it is**: Average revenue generated per website visitor

**How it's calculated**: Total revenue ÷ Total clicks/visits

**Example**: $5,000 revenue from 1,000 clicks = $5.00 EPC

**Why it's crucial**:

* Shows true value of your traffic
* Helps determine profitable advertising spend
* Compares performance across different traffic sources

**Types**:

* **Gross EPC**: Before any deductions
* **Net EPC**: After refunds and fees (more accurate)

## Advanced Metrics

### Customer Acquisition Cost (CAC)

**What it is**: How much you spend to acquire one customer

**How it's calculated**: Total marketing spend ÷ Number of new customers

**Example**: $1,000 ad spend, 50 new customers = $20 CAC

**Why it matters**: Must be less than customer lifetime value to be profitable

***

### Lifetime Value (LTV)

**What it is**: Total revenue a customer generates over their relationship with you

**Includes**: Initial purchase + repeat purchases + upsells

**Key ratio**: LTV should be 3-5x higher than CAC for healthy business

***

## Traffic and Engagement Metrics

*Note: For detailed ad spend metrics including ROAS, CPC, CPA, and CTR, see our [Ad Spend Metrics](/analytics/ad-spend-metrics) guide.*

## Funnel Performance Metrics

### Add to Cart Rate

**What it is**: Percentage of visitors who add products to their cart

**Shows**: Interest level in your products

**Typical range**: 5-15% depending on industry

***

### Cart Abandonment Rate

**What it is**: Percentage of people who add to cart but don't complete purchase

**How it's calculated**: (Carts created - Purchases) ÷ Carts created × 100

**Industry average**: 60-70% (meaning 30-40% complete purchase)

***

### Checkout Completion Rate

**What it is**: Percentage of people who complete purchase after starting checkout

**Target**: 85%+ completion rate

**Low rates indicate**: Checkout process issues, unexpected costs, or technical problems

## Understanding Your Data

### What Good Performance Looks Like

**High-performing funnels typically have**:

* Conversion rate: 3-8%
* AOV: \$75-200+ (varies by industry)
* EPC: \$2-10+
* Cart completion: 85%+
* ROAS: 4:1 or higher

### Red Flags to Watch For

* Conversion rate under 1%
* High traffic but low revenue
* Declining AOV over time
* High refund rates
* Poor mobile performance

### Seasonal Considerations

* Holiday seasons typically show higher AOV
* Summer months may have lower conversion rates
* Back-to-school and Black Friday are peak periods
* Plan campaigns around these patterns

## Improving Your Metrics

### Boost Conversion Rate

* Improve page load speed
* Add customer testimonials and reviews
* Simplify checkout process
* Test different headlines and offers
* Add urgency and scarcity elements
* Optimize for mobile devices

### Increase Average Order Value

* Offer product bundles
* Add "frequently bought together" suggestions
* Create volume discounts
* Implement one-click upsells
* Show related products
* Offer free shipping thresholds

### Optimize Traffic Quality

* Target more specific audiences
* Use negative keywords in ads
* Focus on high-intent traffic sources
* Improve ad copy and targeting
* Test different traffic sources

## Tracking and Monitoring

### Daily Monitoring

Check these metrics daily:

* Conversion rate
* Revenue
* Traffic volume
* Major funnel steps

### Weekly Analysis

Review these weekly:

* AOV trends
* Traffic source performance
* Campaign ROAS
* Customer acquisition costs

### Monthly Deep Dive

Analyze monthly:

* Customer lifetime value
* Seasonal trends
* Funnel optimization opportunities
* Competitive performance

## Common Questions

### "What's a good conversion rate for my industry?"

Conversion rates vary widely by industry, traffic source, and price point. Focus on improving your own baseline rather than comparing to others.

### "Should I focus on more traffic or better conversion rate?"

Generally, improving conversion rate is more cost-effective than buying more traffic. A 1% improvement in conversion rate often has bigger impact than 20% more traffic.

### "How do I know if my AOV is good?"

Compare your AOV to your customer acquisition cost. If AOV is 3-5x higher than CAC, you're in good shape.

### "Why do my metrics fluctuate so much?"

Daily fluctuations are normal due to traffic patterns, seasonality, and external factors. Focus on weekly and monthly trends instead of daily changes.

## Getting More Help

For assistance with:

* Setting up conversion tracking
* Interpreting your specific metrics
* Creating optimization strategies
* Troubleshooting tracking issues

Contact our support team or explore our detailed optimization guides.


# Split Test Analytics
Source: https://docs.elasticfunnels.io/analytics/split-test

Understand split testing metrics, statistical significance, and how to interpret your A/B test results

## At a glance

**Quick Summary**: Split testing lets you compare different versions of your pages to see which performs better. The system automatically tracks visitors, measures conversions, and tells you which version wins with statistical confidence.

**Key Metrics**: Conversion rate, statistical significance, confidence intervals, sample size, and revenue impact.

**Bottom Line**: Run tests until you get statistically significant results, then implement the winning version to improve your funnel performance.

***

## What is Split Testing?

Split testing (also called A/B testing) is a method of comparing two or more versions of a webpage, offer, or element to determine which one performs better. Instead of guessing what works, you let real visitor data decide.

### How It Works

1. **Create Variants**: Make different versions of what you want to test (headlines, buttons, layouts, etc.)
2. **Split Traffic**: Visitors are randomly shown different versions (usually 50/50)
3. **Measure Results**: Track conversions, sales, and other key metrics
4. **Determine Winner**: Statistical analysis tells you which version actually performs better

## Key Metrics Explained

### Conversion Rate

**What it is**: The percentage of visitors who complete your desired action (purchase, signup, etc.)

**Example**: If 100 people visit your page and 5 make a purchase, your conversion rate is 5%

**Why it matters**: This is usually your primary metric for determining which variant performs better

### Custom Goals

**What it is**: Track specific user actions beyond just purchases (email signups, video completions, downloads, etc.)

**How to use**: Define custom goals in your split test settings that match interactions in your page builder

**Example**: Track "email-signup" events to see which variant gets more newsletter subscriptions

### Statistical Significance

**What it is**: A measure of confidence that your results are real, not just random chance

**How to read it**:

* ✅ **Significant**: You can trust the results - implement the winner
* ⚠️ **Not Significant**: Keep testing - results could be due to random variation
* ❌ **Insufficient Data**: Not enough visitors yet to draw conclusions

**Rule of thumb**: Wait for 95% statistical significance before making decisions

### Confidence Intervals

**What it is**: A range showing the likely true performance difference between variants

**Example**: "Variant B improves conversion rate by 2.1% to 7.3%"

* This means Variant B is definitely better than the original
* The true improvement is somewhere between 2.1% and 7.3%

**How to interpret**:

* Range includes zero (e.g., "-1.2% to +4.8%"): **Not significant** - keep testing
* Range is all positive (e.g., "2.1% to 7.3%"): **Winner found** - implement this variant
* Range is all negative (e.g., "-5.2% to -1.1%"): **Loser** - stick with original

### Sample Size

**What it is**: The number of visitors needed to get reliable results

**Why it matters**:

* Too few visitors = unreliable results
* The system calculates minimum sample sizes automatically
* Larger improvements need fewer visitors to detect

### P-Value

**What it is**: The probability of seeing your results (or more extreme) if there were actually no real difference between variants

**How to read it**:

* p \< 0.05: Statistically significant (unlikely to see these results if there's no real difference)
* p > 0.05: Not significant yet (results could reasonably occur even with no real difference)

## Understanding Your Results

### When Results Are Ready

Your split test results are reliable when you have:

* ✅ **Statistical significance** (p-value \< 0.05)
* ✅ **Sufficient sample size** (system will indicate this)
* ✅ **Confidence interval** that doesn't include zero
* ✅ **Test ran for adequate time** (usually at least 1-2 weeks)

### Making Decisions

**Clear Winner**:

* High statistical significance
* Confidence interval shows consistent improvement
* **Action**: Implement the winning variant

**No Clear Winner**:

* Results not statistically significant
* Confidence interval includes zero
* **Action**: Continue testing or try different variants

**Clear Loser**:

* Statistically significant negative results
* **Action**: Stop the test, keep your original version

## Advanced Features

### Automated Winner Selection

**What it is**: The system can automatically select winners when statistical criteria are met

**Configuration options**:

* **Significance Level**: Set your confidence threshold (95%, 99%, etc.)
* **Practical Significance**: Require minimum improvement percentage
* **Sample Size Limits**: Set minimum/maximum visitors per variant
* **Duration Controls**: Set minimum and maximum test durations
* **Guardrail Metrics**: Ensure winners don't hurt other important metrics

### Statistical Settings

**Significance Level**: Control your confidence threshold (0.01 = 99%, 0.05 = 95%)
**Statistical Power**: Probability of detecting real effects (0.8 = 80% power)
**Minimum Detectable Effect**: Smallest improvement you want to detect
**Multiple Testing Correction**: Adjust for testing multiple metrics simultaneously

### Early Stopping & Sequential Testing

**Early Stopping**: Allow tests to conclude as soon as significance is reached
**Sequential Testing**: Check for significance at regular intervals with proper alpha spending
**Alpha Spending Functions**: Pocock, O'Brien-Fleming methods for controlling false positives

### Timezone Support

All dates and times are displayed in your brand's configured timezone for accurate local time tracking.

## Best Practices

### Before Starting

* **Test one thing at a time**: Don't change multiple elements simultaneously
* **Have a clear hypothesis**: Know what you expect and why
* **Set success metrics**: Define what "winning" means before you start
* **Plan for adequate traffic**: Ensure you have enough visitors for reliable results
* **Configure automation**: Set up automated winner selection criteria if desired

### During Testing

* **Don't peek too early**: Wait for statistical significance
* **Run for full business cycles**: Include weekends, different days
* **Avoid external changes**: Don't make other changes during the test
* **Monitor for technical issues**: Ensure both variants are working properly

### After Results

* **Implement winners quickly**: Don't delay acting on clear results
* **Document learnings**: Keep track of what worked and what didn't
* **Plan next tests**: Use insights to inform future testing ideas
* **Monitor post-implementation**: Ensure results hold up after full rollout

## Common Questions

### "How long should I run my test?"

Run until you achieve statistical significance AND have adequate sample size. This usually takes 1-4 weeks depending on your traffic volume.

### "Can I stop early if I see good results?"

With early stopping enabled, you can stop as soon as statistical significance is reached. However, ensure you've met minimum duration and sample size requirements.

### "What if my test shows no winner?"

This is valuable information! It means your variants perform similarly. Try testing more dramatic changes or different elements.

### "How does automated winner selection work?"

The system runs checks every 5 minutes and can automatically select winners based on your configured criteria:

* Statistical significance threshold
* Minimum sample size requirements
* Practical significance thresholds
* Guardrail metric protection
* Duration limits

### "What are guardrail metrics?"

Metrics that protect your business - the system ensures the winning variant doesn't significantly hurt important metrics like revenue, profit, or user experience.

### "How much improvement should I expect?"

Typical improvements range from 5-30%. Small improvements (1-2%) are hard to detect and may not be worth implementing.

### "Can I test more than 2 variants?"

Yes, but more variants require more traffic and time to reach significance. Start with 2 variants when possible.

## Configuration Modes

### Simple Mode

Choose from preset configurations designed for common testing scenarios:

* **Sprint Test**: Ultra-fast results in 3-7 days for obvious changes
* **Standard Test**: 7-14 days for reliable results on most changes
* **Deep Test**: 14-30 days for thorough testing of important changes
* **Revenue Test**: Optimized for revenue and AOV improvements
* **Engagement Test**: Focus on user engagement and interaction metrics

### Advanced Mode

Full control over all statistical parameters:

* Custom significance levels and statistical power
* Bayesian vs Frequentist statistical methods
* Sequential testing with alpha spending functions
* Practical significance thresholds
* Custom sample size limits and duration controls

## Revenue Impact

Split testing directly impacts your bottom line by:

* **Increasing conversion rates**: More visitors become customers
* **Improving average order value**: Better offers and upsells
* **Reducing bounce rates**: More engaging content keeps visitors on-site
* **Optimizing customer lifetime value**: Better experiences lead to repeat customers

Even small improvements compound over time. A 10% conversion rate improvement on a page with 1000 monthly visitors and $100 average order value generates an extra $1,000 monthly revenue.

### Automated Optimization

With automated winner selection enabled, your funnels continuously optimize themselves:

* Tests run automatically based on your criteria
* Winners are selected when statistical thresholds are met
* Traffic is redirected to winning variants without manual intervention
* Guardrail metrics protect against negative impacts

## Getting Help

If you need assistance with:

* Setting up tests
* Interpreting results
* Troubleshooting issues
* Planning testing strategies

Contact our support team or check our detailed guides for specific testing scenarios.


# Tracking Metrics
Source: https://docs.elasticfunnels.io/analytics/tracking-metrics

Detailed tracking metrics for user behavior, engagement, and funnel performance analysis

## At a glance

**Quick Summary**: Tracking metrics provide detailed insights into user behavior, engagement patterns, and funnel performance. These metrics help you understand how users interact with your content and identify optimization opportunities.

**Most Important**: Sessions, Page Views, Engagement Rate, and Session Duration are your core tracking performance indicators.

**Bottom Line**: Better tracking leads to better optimization. Monitor these metrics to understand user behavior and improve funnel performance.

***

## Core Tracking Metrics

### Sessions

**What it is**: Individual visits to your website or funnel, regardless of duration

**How it's tracked**: Unique session identifiers that expire after inactivity

**Example**: A user visits your site, browses for 10 minutes, leaves, then returns 2 hours later = 2 sessions

**Why it matters**:

* Foundation metric for calculating rates and averages
* Shows traffic volume and user interest
* Used to calculate conversion rates and engagement metrics

**Technical details**:

* Session expires after 30 minutes of inactivity (configurable)
* New session starts with each new visit
* Cross-device sessions may be counted separately

***

### Page Views

**What it is**: Total number of pages viewed across all sessions

**How it's tracked**: Each page load or route change triggers a page view event

**Different from sessions**: Multiple page views can occur within a single session

**Why it's valuable**:

* Shows content consumption patterns
* Indicates user engagement depth
* Helps identify popular content
* Used for calculating pages per session

**Optimization insights**:

* High page views per session indicate good engagement
* Low page views may suggest navigation issues
* Track which pages drive the most views

***

### Unique Clicks

**What it is**: Number of distinct sessions that resulted in at least one click

**How it's calculated**: Cardinality count of unique session IDs with click events

**Different from total clicks**: Counts each session only once, regardless of multiple clicks

**Why it's important**:

* Shows actual user engagement vs bot traffic
* More accurate than total clicks for engagement analysis
* Better metric for calculating click-through rates

**Use cases**:

* Measuring campaign effectiveness
* Calculating true engagement rates
* Identifying quality traffic sources

***

## Engagement Metrics

### Engagement Rate

**What it is**: Percentage of sessions that include meaningful user interactions

**How it's calculated**: (Sessions with Engagements ÷ Total Sessions) × 100

**What counts as engagement**:

* Clicks on interactive elements
* Form submissions
* Video plays
* Downloads
* Time-based engagement thresholds

**Why it's crucial**:

* Shows content quality and relevance
* Indicates user interest and intent
* Helps identify optimization opportunities
* Correlates with conversion potential

**Good benchmarks**:

* 40-60%: Typical performance
* 60-80%: Good performance
* 80%+: Excellent performance

***

### Session Duration

**What it is**: Average time users spend on your site per session

**How it's calculated**: Total Time on Page ÷ Number of Sessions

**Technical measurement**: Time between first page load and last recorded activity

**Why it matters**:

* Indicates content quality and user interest
* Shows if users find value in your content
* Helps identify pages that hold attention
* Correlates with conversion likelihood

**Ways to improve**:

* Improve content quality and relevance
* Enhance page loading speed
* Add engaging interactive elements
* Optimize content structure and flow

***

### Time on Page

**What it is**: Total time users spend viewing specific pages

**How it's measured**: Time between page load and next page load or session end

**Aggregation**: Sum of all time spent across all sessions

**Use for**:

* Identifying most engaging content
* Understanding user behavior patterns
* Optimizing page content and layout
* Calculating average session duration

**Limitations**:

* Last page of session may not be accurately measured
* Inactive tabs may inflate time measurements
* Requires JavaScript-based tracking for accuracy

***

## Funnel-Specific Metrics

### Funnel Clicks

**What it is**: Total number of clicks on funnel-specific elements

**Includes**:

* CTA button clicks
* Product link clicks
* Navigation clicks within funnel
* Form field interactions

**Why track separately**: Distinguishes funnel engagement from general site navigation

**Optimization insights**:

* High funnel clicks indicate good user flow
* Low clicks may suggest unclear CTAs
* Click patterns show user journey preferences

***

### Funnel Click-Through Rate (CTR)

**What it is**: Percentage of sessions that result in funnel clicks

**How it's calculated**: (Funnel Clicks ÷ Sessions) × 100

**Why it's important**:

* Shows funnel effectiveness
* Indicates CTA performance
* Helps optimize user flow
* Measures engagement quality

**Optimization tactics**:

* Test different CTA designs
* Improve CTA placement
* Optimize messaging and copy
* Reduce friction in user flow

***

### Add to Cart Rate

**What it is**: Percentage of visitors who add products to their cart

**How it's calculated**: (Add to Cart Events ÷ Sessions) × 100

**Why it's critical**:

* Shows product interest level
* Indicates pricing acceptance
* Measures funnel effectiveness
* Predicts conversion potential

**Typical ranges**: 5-15% depending on industry and traffic source

**Improvement strategies**:

* Optimize product presentation
* Improve pricing strategy
* Add social proof elements
* Simplify add-to-cart process

***

## Advanced Tracking Metrics

### Engagement Time

**What it is**: Total time users spend actively engaging with content

**Different from session duration**: Only counts active interaction time

**Measurement criteria**:

* Mouse movement and clicks
* Keyboard interactions
* Scroll activity
* Video/audio engagement

**Why it's more accurate**: Filters out inactive time and background tabs

**Use cases**:

* Content quality assessment
* User experience optimization
* Engagement comparison across pages
* True attention measurement

***

### Split Test Views

**What it is**: Number of times different variations in A/B tests are viewed

**How it's tracked**: Separate counting for each test variation

**Why it's essential**:

* Ensures statistical significance
* Validates test results
* Helps determine winning variations
* Guides optimization decisions

**Best practices**:

* Ensure even traffic distribution
* Track sufficient sample sizes
* Monitor for external factors
* Document test parameters

***

### UTM Parameter Tracking

**What it is**: Tracking of campaign parameters in URLs for attribution

**Standard parameters**:

* utm\_source: Traffic source (google, facebook, email)
* utm\_medium: Marketing medium (cpc, social, email)
* utm\_campaign: Campaign name
* utm\_term: Keyword (for paid search)
* utm\_content: Ad content differentiation

**Why it's crucial**:

* Accurate campaign attribution
* ROI measurement by source
* Optimization insights
* Budget allocation guidance

**Implementation tips**:

* Use consistent naming conventions
* Document parameter standards
* Validate tracking setup
* Regular attribution analysis

***

## E-commerce Specific Metrics

### Add to Carts

**What it is**: Total number of add-to-cart events across all sessions

**Different from add-to-cart rate**: Raw count vs percentage

**Why track both**:

* Volume understanding (total events)
* Performance measurement (rate)
* Trend analysis over time
* Capacity planning

**Optimization focus**:

* Product page improvements
* Pricing strategy adjustments
* User experience enhancements
* Inventory management insights

***

### Cart Conversion Rate

**What it is**: Percentage of cart additions that result in purchases

**How it's calculated**: (Purchases ÷ Add to Carts) × 100

**Industry averages**: 30-40% completion rate

**Why it's critical**:

* Shows checkout process effectiveness
* Identifies abandonment issues
* Measures pricing acceptance
* Indicates trust and security perception

**Improvement strategies**:

* Simplify checkout process
* Add trust signals and security badges
* Optimize payment options
* Reduce unexpected costs

***

## Time-Based Metrics

### Time on Page Before First Purchase

**What it is**: Average time users spend on site before making their first purchase

**Why it's valuable**:

* Shows consideration period length
* Helps optimize content strategy
* Indicates decision-making patterns
* Guides retargeting timing

**Use for**:

* Content planning and development
* Email sequence timing
* Retargeting campaign setup
* Sales process optimization

***

### Affiliate Clicks

**What it is**: Clicks on affiliate or partner links within your funnel

**Tracking considerations**:

* Separate from internal navigation
* Attribution to specific partners
* Commission calculation basis
* Performance measurement

**Why monitor**:

* Partner relationship management
* Revenue attribution
* Commission accuracy
* Partnership optimization

***

## Implementation and Setup

### Basic Tracking Requirements

**Essential events to track**:

* Page views and route changes
* Click events on key elements
* Form submissions and interactions
* Session start and end times
* User engagement indicators

**Technical setup**:

* JavaScript tracking code
* Event listener implementation
* Session management
* Data validation and cleaning

***

### Advanced Tracking Features

**Enhanced data collection**:

* User agent and device information
* Geographic location data
* Referrer and traffic source
* Custom event parameters
* Cross-device identification

**Privacy considerations**:

* GDPR compliance requirements
* Cookie consent management
* Data anonymization options
* User opt-out mechanisms

***

## Data Quality and Validation

### Common Tracking Issues

**Bot traffic filtering**:

* Identify and exclude automated traffic
* Validate human interaction patterns
* Monitor for unusual activity spikes
* Implement bot detection mechanisms

**Data accuracy checks**:

* Validate event firing consistency
* Check for duplicate events
* Monitor tracking code errors
* Verify cross-browser compatibility

***

### Performance Monitoring

**Tracking performance metrics**:

* Event processing speed
* Data collection accuracy
* System reliability uptime
* Error rate monitoring

**Ways to improve**:

* Minimize tracking code impact
* Implement efficient data collection
* Use asynchronous loading
* Regular performance audits

***

## Reporting and Analysis

### Real-Time Monitoring

**Key metrics for immediate attention**:

* Current active sessions
* Real-time conversion events
* Traffic source performance
* System health indicators

**Alert setup**:

* Unusual traffic patterns
* Conversion rate drops
* Technical tracking issues
* Performance threshold breaches

***

### Historical Analysis

**Trend identification**:

* Long-term performance patterns
* Seasonal behavior changes
* Growth trajectory analysis
* Comparative period performance

**Strategic insights**:

* User behavior evolution
* Content performance trends
* Channel effectiveness changes
* Optimization opportunity identification

***

## Getting More Help

For assistance with:

* Tracking implementation setup
* Custom event configuration
* Data analysis and interpretation
* Performance optimization strategies

Contact our support team or explore our detailed tracking implementation guides.


# Video Metrics
Source: https://docs.elasticfunnels.io/analytics/video-metrics

Track video engagement and performance metrics across different video players and platforms

<Warning>
  **Player Compatibility Notice**: Video tracking accuracy depends on your video player implementation. Some players may not properly track all metrics or may have limited support.

  **Known Limitations**:

  * **vTurb V2**: Only partially supported - some metrics may not track accurately
  * **Custom players**: Must implement standard video events and have `video` tag name.

  **Recommendation**: Test your specific player setup to verify which metrics are accurately tracked before relying on the data for optimization decisions.
</Warning>

***

## At a glance

**Quick Summary**: Video metrics help you understand how users interact with video content in your funnels. These metrics work with various video players and provide insights into engagement, completion rates, and viewing behavior.

**Most Important**: Video Play Rate, Video Completion Rate, and Average Watch Time are your core video performance indicators.

**Bottom Line**: Higher video engagement typically leads to better conversion rates. Monitor these metrics to optimize your video content and placement.

**Player Compatibility**: These metrics work with most modern video players including HTML5, Vimeo, YouTube, Wistia, and custom players that support standard video events.

***

## Core Video Engagement Metrics

### Video Play Rate

**What it is**: The percentage of visitors who start playing your video

**How it's calculated**: (Video Play Sessions ÷ Total Sessions) × 100

**Example**: 500 video plays from 1,000 sessions = 50% play rate

**Why it matters**:

* Shows how compelling your video thumbnail and placement are
* Indicates initial user interest in your content
* Helps optimize video positioning and preview images

**Good benchmarks**:

* 30-50%: Good performance
* 50-70%: Excellent performance
* 70%+: Outstanding performance

**Player requirements**: Requires video player to fire 'play' events

***

### Video Completion Rate

**What it is**: The percentage of video viewers who watch the entire video

**How it's calculated**: (Video Completion Sessions ÷ Video Play Sessions) × 100

**Example**: 200 completions from 500 plays = 40% completion rate

**Why it matters**:

* Measures content quality and engagement
* Indicates if video length is appropriate
* Shows effectiveness of your video content

**Good benchmarks**:

* 20-40%: Typical performance
* 40-60%: Good performance
* 60%+: Excellent performance

**Player requirements**: Requires video player to fire 'ended' or completion events

***

### Average Video Watch Time

**What it is**: The average amount of time users spend watching your video

**How it's calculated**: Total Video Watch Time ÷ Video Sessions

**Example**: 5,000 seconds total watch time from 100 sessions = 50 seconds average

**Why it matters**:

* Shows actual engagement level with your content
* Helps identify optimal video length
* Indicates where viewers typically drop off

**Optimization tips**:

* Hook viewers in the first 10 seconds
* Keep key messages early in the video
* Test different video lengths
* Add captions for better accessibility

**Player requirements**: Requires video player to track time watched accurately

***

## Advanced Video Metrics

### Video Unmute Rate

**What it is**: The percentage of video viewers who unmute the video (for autoplay videos)

**How it's calculated**: (Video Unmute Sessions ÷ Video Play Sessions) × 100

**Why it matters**:

* Critical for autoplay video strategies
* Shows active engagement vs passive viewing
* Helps optimize audio content and captions

**Good benchmarks**:

* 10-20%: Typical for autoplay videos
* 20-30%: Good performance
* 30%+: Excellent performance

**Player requirements**: Requires video player to track mute/unmute events

***

### Video CTA Show Rate

**What it is**: The percentage of video sessions where a call-to-action is displayed

**How it's calculated**: (Video CTA Shows ÷ Video Sessions) × 100

**Why it matters**:

* Measures CTA visibility and timing
* Helps optimize when CTAs appear
* Shows potential conversion opportunities

**Ways to improve**:

* Show CTAs at optimal engagement points
* Test different CTA timing
* A/B test CTA designs and messaging

**Player requirements**: Requires custom implementation to track CTA displays

***

### Total Video Watch Time

**What it is**: The cumulative time all users spend watching your video content

**Use for**:

* Understanding overall content consumption
* Calculating average watch times
* Measuring total engagement volume

**Why it's valuable**:

* Shows aggregate content value
* Helps justify video production costs
* Indicates content popularity trends

***

## Video Session Metrics

### Video Sessions

**What it is**: Total number of sessions where video content was accessed

**Different from**: Video plays (some sessions may not result in plays)

**Use for**:

* Understanding video exposure
* Calculating play rates
* Measuring video page traffic

***

### Video Play Sessions

**What it is**: Number of sessions where users actually started playing the video

**Why track separately**: Distinguishes between video exposure and actual engagement

**Use for**:

* Calculating completion rates
* Understanding true video engagement
* Optimizing video placement and thumbnails

***

### Video Completion Sessions

**What it is**: Number of sessions where users watched the video to completion

**Critical for**:

* Measuring content effectiveness
* Understanding user commitment
* Optimizing video length and content

***

## Player-Specific Considerations

### HTML5 Video Players

**Supported events**: play, pause, ended, timeupdate, volumechange
**Tracking accuracy**: High - direct event access
**Setup requirements**: Standard HTML5 video element with event listeners

### YouTube Embedded Videos

**Supported events**: onStateChange, onPlaybackQualityChange
**Tracking accuracy**: Good - via YouTube API
**Setup requirements**: YouTube IFrame API integration
**Limitations**: Some events may be restricted by YouTube policies

### Vimeo Embedded Videos

**Supported events**: play, pause, ended, timeupdate
**Tracking accuracy**: High - via Vimeo Player API
**Setup requirements**: Vimeo Player SDK integration
**Benefits**: Detailed analytics and customization options

### Wistia Videos

**Supported events**: play, pause, end, timechange
**Tracking accuracy**: Excellent - API-level tracking
**Setup requirements**: Wistia embed code with API enabled
**Benefits**: Built-in heatmaps and engagement analytics

### vturb v2 Player

**Support level**: Partially supported
**Tracking accuracy**: Limited - some metrics may not be available
**Known issues**:

* May not fire all standard video events consistently
* Some engagement metrics might not track properly
* Completion tracking may be unreliable
  **Recommendation**: Verify specific metrics work in your implementation before depending on them

***

### Custom Video Players

**Requirements**: Must implement standard video events
**Tracking accuracy**: Varies by implementation
**Setup**: Custom event tracking implementation needed
**Considerations**: Ensure consistent event naming and timing

***

## Implementation Requirements

### Basic Tracking Setup

**Required events**:

* Video load/ready
* Play start
* Pause
* Video end/completion
* Time updates

**Optional events**:

* Mute/unmute
* Quality changes
* Fullscreen toggle
* Seek events

### Data Collection

**Essential data points**:

* Session ID
* Video ID or URL
* Timestamp
* Event type
* Current time position
* Video duration

**Enhanced tracking**:

* User agent
* Device type
* Connection speed
* Video quality
* Engagement score

***

## Optimization Strategies

### Improving Play Rates

**Video thumbnails**:

* Use compelling, high-quality thumbnails
* Test different thumbnail styles
* Include faces or action shots
* Avoid misleading thumbnails

**Video placement**:

* Position videos prominently
* Use autoplay strategically
* Add play button overlays
* Optimize for mobile viewing

### Increasing Completion Rates

**Content optimization**:

* Hook viewers in first 10 seconds
* Keep videos concise and focused
* Use engaging visuals and audio
* Include clear value propositions

**Technical optimization**:

* Ensure fast loading times
* Optimize for different devices
* Provide quality options
* Add captions and transcripts

### Maximizing Watch Time

**Content strategies**:

* Structure content with clear progression
* Use storytelling techniques
* Include interactive elements
* Maintain consistent pacing

**Technical strategies**:

* Minimize buffering issues
* Optimize video compression
* Provide smooth playback
* Enable quality adaptation

***

## Common Issues and Solutions

### Low Play Rates

**Possible causes**:

* Poor thumbnail quality
* Unclear video purpose
* Slow loading times
* Poor placement

**Solutions**:

* A/B test thumbnails
* Add descriptive titles
* Optimize video loading
* Improve video positioning

### High Drop-off Rates

**Possible causes**:

* Slow start to content
* Poor audio/video quality
* Content doesn't match expectations
* Too long for the context

**Solutions**:

* Front-load key information
* Improve production quality
* Align content with promises
* Test shorter versions

### Technical Tracking Issues

**Common problems**:

* Events not firing
* Duplicate event tracking
* Cross-browser compatibility
* Mobile tracking issues
* Player-specific limitations (e.g., vturb v2 partial support)

**Solutions**:

* Test across all browsers
* Implement event deduplication
* Use progressive enhancement
* Test on actual mobile devices
* Verify player-specific event support before implementation

**vturb v2 Specific Issues**:

* Some video events may not fire consistently
* Consider alternative tracking methods for critical metrics
* Test thoroughly in your specific implementation
* Have fallback tracking for important conversion events

***

## Reporting and Analysis

### Daily Monitoring

**Key metrics to check**:

* Video play rate
* Completion rate
* Average watch time
* Technical issues

### Weekly Analysis

**Deeper insights**:

* Content performance trends
* Device and browser breakdowns
* User behavior patterns
* Conversion correlation

### Monthly Optimization

**Strategic reviews**:

* Content strategy effectiveness
* Technical performance optimization
* Player technology evaluation
* ROI analysis of video content

***

## Getting More Help

For assistance with:

* Video player integration
* Custom tracking implementation
* Performance optimization
* Analytics setup and interpretation

Contact our support team or explore our detailed video integration guides.


# Authentication
Source: https://docs.elasticfunnels.io/api-reference/authentication

Learn how to authenticate your API requests

## Overview

The ElasticFunnels API uses **API keys** for authentication. Each API key is tied to a specific user and project (brand), inheriting all the permissions of that user for that project.

<Warning>
  Keep your API keys secure! Never share them publicly or commit them to version control. Treat them like passwords.
</Warning>

## Generating an API Key

1. Navigate to your project dashboard
2. Go to **Settings** → **API**
3. Click **Generate API Key**
4. Copy and securely store your API key

<Note>
  You can regenerate your API key at any time, but this will immediately invalidate the old key. Make sure to update any integrations using the old key.
</Note>

## Using Your API Key

Include your API key in the request header using the `EF-Access-Key` header:

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/pages/all \
  -H "EF-Access-Key: your_api_key_here"
```

```javascript JavaScript theme={null}
const headers = {
  'EF-Access-Key': 'your_api_key_here',
  'Content-Type': 'application/json'
};

const response = await fetch('https://app.elasticfunnels.io/api/brands/{brand_id}/pages/all', {
  headers: headers
});
```

```python Python theme={null}
import requests

headers = {
    'EF-Access-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://app.elasticfunnels.io/api/brands/{brand_id}/pages/all',
    headers=headers
)
```

```php PHP theme={null}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://app.elasticfunnels.io/api/brands/' . $brandId . '/pages/all');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'EF-Access-Key: your_api_key_here',
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
```

## Authentication Errors

If authentication fails, you'll receive one of the following responses:

### Invalid API Key

```json theme={null}
{
  "message": "Invalid API key"
}
```

**Status Code:** `401 Unauthorized`

### No Brand Access

```json theme={null}
{
  "message": "Invalid API key or brand access denied"
}
```

**Status Code:** `401 Unauthorized`

This error occurs when:

* Your API key is valid but doesn't have access to the specified brand/project
* You're trying to access a project you're not a member of

### Missing API Key

If you don't include the `EF-Access-Key` header, you'll be redirected to the login page (for browser requests) or receive a 404 error (for API requests).

## API Key Scope and Permissions

<Info>
  Your API key inherits all permissions from your user account for the specific project.
</Info>

API keys are:

* **User-specific**: Each key is tied to your user account
* **Project-specific**: Each key is tied to a specific project (brand)
* **Permission-aware**: Your API requests have the same permissions as your user role (Owner, Admin, Editor, etc.)

### Example Permission Scenarios

**Owner/Admin**: Full access to all endpoints including team management, billing, and settings

**Editor**: Access to content management endpoints (pages, products, funnels) but not billing or team management

**Viewer**: Read-only access to analytics and content

## Best Practices

<CardGroup>
  <Card title="Rotate Keys Regularly" icon="rotate">
    Regenerate your API keys periodically for enhanced security
  </Card>

  <Card title="Use Environment Variables" icon="code">
    Store API keys in environment variables, never in your codebase
  </Card>

  <Card title="One Key Per Integration" icon="layer-group">
    Use separate API keys for different integrations to easily revoke access
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Keep track of which integrations use which keys
  </Card>
</CardGroup>

## Regenerating Your API Key

If your API key is compromised or you need to revoke access:

1. Go to **Settings** → **API**
2. Click **Regenerate API Key**
3. Confirm the action
4. Update all integrations with the new key

<Warning>
  Regenerating an API key immediately invalidates the old key. Any integrations using the old key will stop working until updated.
</Warning>

## Testing Your Authentication

You can test your API key with a simple GET request to retrieve your brand details:

```bash theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id} \
  -H "EF-Access-Key: your_api_key_here"
```

A successful response will return your project information with a `200 OK` status.


# Affiliates
Source: https://docs.elasticfunnels.io/api-reference/endpoints/affiliates

Manage affiliate accounts, commissions, and payout processing

<Note>
  Affiliate endpoints sit under `/api/brands/{brand}/affiliates/` with `moduleAccess:affiliates` middleware. Authenticate with `EF-Access-Key`.
</Note>

***

## List Affiliates

```
GET /api/brands/{brand}/affiliates
```

<ParamField type="number">
  Results per page (1–100, default: 25)
</ParamField>

<ParamField type="string">
  Filter by type: `external` or `affcenter`
</ParamField>

<ParamField type="string">
  Search by name or merchant account ID
</ParamField>

<ParamField type="string">
  `newest`, `oldest`, `created_at`, `updated_at`
</ParamField>

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/affiliates \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "current_page": 1,
    "data": [
      {
        "id": 5,
        "name": "John Smith",
        "email": "john@affiliate.com",
        "status": "active",
        "type": "external",
        "commission_rate": 30,
        "commission_type": "percent",
        "merchant": { "id": 1, "merchant": "NMI", "account_id": "123" },
        "commissionGroup": null,
        "brand_id": 42
      }
    ],
    "per_page": 25,
    "total": 18,
    "last_page": 1
  }
  ```
</ResponseExample>

***

## List All Affiliates (Unpaginated)

```
GET /api/brands/{brand}/affiliates/all
```

Returns `id`, `name`, `type`, and `merchant` for all affiliates — useful for dropdowns.

***

## Quick Access Stats

```
GET /api/brands/{brand}/affiliates/quick-access
```

<ResponseExample>
  ```json Response theme={null}
  {
    "all": 18,
    "external": 12,
    "affcenter": 6
  }
  ```
</ResponseExample>

***

## Organization Affiliates Options

Search affiliates from the organization's affiliate center — used for linking org affiliates to a brand.

```
GET /api/brands/{brand}/affiliates/organization-affiliates-options
```

<ParamField type="string">
  Search by name, email, or nickname
</ParamField>

<ParamField type="number">
  Ensure this affiliate is included even if outside the search results
</ParamField>

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "id": 3,
      "name": "Jane Affiliate",
      "email": "jane@example.com",
      "nickname": "jane_aff",
      "displayLabel": "Jane Affiliate (jane@example.com)"
    }
  ]
  ```
</ResponseExample>

***

## Get Affiliate

```
GET /api/brands/{brand}/affiliates/{affiliate}
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 5,
    "name": "John Smith",
    "email": "john@affiliate.com",
    "phone": null,
    "status": "active",
    "type": "external",
    "commission_rate": 30,
    "commission_type": "percent",
    "is_whitelisted": false,
    "merchant_id": 1,
    "merchant": null
  }
  ```
</ResponseExample>

***

## Create Affiliate

```
POST /api/brands/{brand}/affiliates
```

<ParamField type="string">
  Affiliate display name (max 255)
</ParamField>

<ParamField type="string">
  `active`, `disabled`, `blacklisted`, `pending`, `pending_email`, or `pending_approve`
</ParamField>

<ParamField type="string">
  Affiliate email. Must be unique per brand.
</ParamField>

<ParamField type="string">
  Phone number (max 255)
</ParamField>

<ParamField type="string">
  `external` (manually managed) or `affcenter` (linked to org affiliate center)
</ParamField>

<ParamField type="number">
  Commission percentage or fixed amount
</ParamField>

<ParamField type="string">
  `percent` or `fixed`
</ParamField>

<ParamField type="number">
  Link to a brand merchant integration
</ParamField>

<ParamField type="boolean">
  Bypass approval requirements
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/affiliates \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "email": "john@affiliate.com",
    "status": "active",
    "type": "external",
    "commission_rate": 30,
    "commission_type": "percent"
  }'
```

<ResponseExample>
  ```json 200 Created theme={null}
  {
    "affiliate": {
      "id": 5,
      "name": "John Smith",
      "email": "john@affiliate.com",
      "status": "active",
      "type": "external",
      "commission_rate": 30,
      "commission_type": "percent",
      "brand_id": 42,
      "created_at": "2024-12-11T10:00:00.000000Z"
    }
  }
  ```

  ```json 422 Duplicate email theme={null}
  {
    "errors": {
      "email": ["The email has already been taken."]
    }
  }
  ```

  ```json 403 Plan limit theme={null}
  {
    "error": "Upgrade required to create affiliates",
    "plan_error": {
      "message": "Your current plan does not allow creating affiliates.",
      "upgrade_info": {}
    }
  }
  ```
</ResponseExample>

***

## Update Affiliate

```
PUT /api/brands/{brand}/affiliates/{affiliate}
```

Same body as Create — all fields optional on update.

***

## Delete Affiliate

```
DELETE /api/brands/{brand}/affiliates/{affiliate}
```

<ResponseExample>
  ```json Response theme={null}
  { "success": true }
  ```
</ResponseExample>

***

## Export Affiliates

```
POST /api/brands/{brand}/affiliates/export
```

<ParamField type="array">
  Filter conditions (same as list query params)
</ParamField>

<ParamField type="array">
  Limit export to specific affiliate IDs
</ParamField>

<ParamField type="array">
  Columns to include in the export
</ParamField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "message": "Export started. You will receive an email when it is ready."
  }
  ```
</ResponseExample>

***

## Payouts

Payouts represent commission payments owed to affiliates for a billing period.

### List Payouts

```
GET /api/brands/{brand}/affiliates/payouts
```

<ParamField type="number">
  Filter by affiliate ID
</ParamField>

<ParamField type="string">
  Filter by status: `pending`, `approved`, `paid`, `rejected`, `cancelled`
</ParamField>

<ParamField type="number">
  Results per page (1–100, default: 25)
</ParamField>

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/affiliates/payouts?status=pending" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "current_page": 1,
    "data": [
      {
        "id": 3,
        "brand_affiliate_id": 5,
        "status": "pending",
        "amount": 450.00,
        "currency": "USD",
        "period_start": "2024-12-01",
        "period_end": "2024-12-31",
        "conversions_count": 15,
        "affiliate": { "id": 5, "name": "John Smith" },
        "created_at": "2025-01-01T00:00:00Z"
      }
    ],
    "per_page": 25,
    "total": 4
  }
  ```
</ResponseExample>

### Create Payout

Generate a payout for an affiliate based on their conversions in a date range.

```
POST /api/brands/{brand}/affiliates/payouts
```

<ParamField type="number">
  Affiliate ID to create the payout for
</ParamField>

<ParamField type="string">
  Start date (ISO 8601)
</ParamField>

<ParamField type="string">
  End date (ISO 8601, must be on or after `period_start`)
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/affiliates/payouts \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_affiliate_id": 5,
    "period_start": "2024-12-01",
    "period_end": "2024-12-31"
  }'
```

### Update Payout Status

```
PUT /api/brands/{brand}/affiliates/payouts/{payout}
```

<ParamField type="string">
  `approved`, `rejected`, `paid`, or `cancelled`
</ParamField>

<ParamField type="string">
  Required when `status` is `rejected` (max 1000 chars)
</ParamField>

<ParamField type="string">
  Required when `status` is `paid` (e.g. `bank_transfer`, `paypal`)
</ParamField>

<ParamField type="string">
  Optional payment reference/transaction ID (max 255)
</ParamField>

```bash cURL — mark as paid theme={null}
curl -X PUT https://app.elasticfunnels.io/api/brands/{brand_id}/affiliates/payouts/3 \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"status": "paid", "payment_method": "bank_transfer", "payment_reference": "TXN-987654"}'
```

### Upload Payout Invoice

```
POST /api/brands/{brand}/affiliates/payouts/{payout}/invoice
```

<ParamField type="file">
  Invoice PDF file (multipart/form-data)
</ParamField>

***

## Notes

<Info>
  * `type: "affcenter"` affiliates are linked to your organization's affiliate center and require the `viewOrganizationAffiliates` permission
  * Some organization portals require an uploaded invoice before a payout can be marked as `paid`
  * Payout amounts are calculated from the affiliate's commissions on approved conversions within the period
</Info>


# Analytics
Source: https://docs.elasticfunnels.io/api-reference/endpoints/analytics

Retrieve analytics metrics and performance data

## Get Available Metrics

Retrieve the list of available metrics you can track.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Filter metrics relevant to split tests (optional)
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/analytics/metrics
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/analytics/metrics \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "revenue": {
      "type": "revenue",
      "name": "Revenue",
      "base": "revenue",
      "color": "#10b981",
      "icon": "<svg>...</svg>",
      "info": "Total revenue from orders",
      "group_name": "Sales",
      "modules": ["conversions"]
    },
    "sales": {
      "type": "sales",
      "name": "Sales",
      "base": "sales",
      "color": "#3b82f6",
      "group_name": "Sales",
      "modules": ["conversions"]
    },
    "page_views": {
      "type": "page_views",
      "name": "Page Views",
      "base": "page_views",
      "group_name": "Traffic",
      "modules": ["tracking"]
    }
  }
  ```
</ResponseExample>

***

## Get Metrics Data

Retrieve actual metrics values for a date range.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Start date (ISO 8601 format)
</ParamField>

<ParamField type="string">
  End date (ISO 8601 format)
</ParamField>

<ParamField type="string">
  Timezone (e.g., "America/New\_York")
</ParamField>

<ParamField type="array">
  Array of metric keys to retrieve
</ParamField>

<ParamField type="string">
  Filter by specific field values (e.g., `filter[aff_id]=123`)
</ParamField>

<ParamField type="string">
  Filter by specific page
</ParamField>

<ParamField type="string">
  Filter by specific split test
</ParamField>

<ParamField type="string">
  Optional. Only use when your integration or account documentation specifies a value.
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/analytics/metrics/data
```

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/analytics/metrics/data?start=2024-12-01T00:00:00Z&end=2024-12-10T23:59:59Z&selected_metrics[]=revenue&selected_metrics[]=sales&selected_metrics[]=page_views" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "revenue": {
      "value": 15750.00,
      "formatted_value": "$15,750.00",
      "previous_value": 12300.00,
      "change": 28.05,
      "change_symbol": "+",
      "current_range": "Dec 1 - Dec 10",
      "previous_range": "Nov 20 - Nov 30",
      "previous_range_label": "Previous Period",
      "lower_is_better": false,
      "neutral": false
    },
    "sales": {
      "value": 315,
      "formatted_value": "315",
      "previous_value": 246,
      "change": 28.05,
      "change_symbol": "+",
      "lower_is_better": false
    },
    "page_views": {
      "value": 10500,
      "formatted_value": "10,500",
      "previous_value": 8750,
      "change": 20.00,
      "change_symbol": "+"
    }
  }
  ```
</ResponseExample>

***

## Get Analytics Cards

For the full card catalog (batch vs per-card URLs, subscription analytics, split-test charts), see **[Analytics dashboard cards](/api-reference/endpoints/analytics-cards)**.

Retrieve specialized analytics cards data (video analytics, fulfillment metrics, etc.).

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Start date (ISO 8601 format)
</ParamField>

<ParamField type="string">
  End date (ISO 8601 format)
</ParamField>

<ParamField type="array">
  Array of card types to retrieve
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/analytics/metrics/cards
```

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/analytics/metrics/cards?start=2024-12-01T00:00:00Z&end=2024-12-10T23:59:59Z&enabled_cards[]=video_play_rate&enabled_cards[]=time_on_page_before_purchase" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "cards": {
      "video_analytics": {
        "video_play_rate": {
          "value": 0.65,
          "formatted_value": "65%"
        },
        "average_video_watch_time": {
          "value": 185.5,
          "formatted_value": "3:05"
        }
      },
      "advanced_metrics": {
        "time_on_page_before_purchase": {
          "value": 320,
          "formatted": "5:20",
          "sample_size": 315
        }
      }
    },
    "enabled_cards": ["video_play_rate", "time_on_page_before_purchase"],
    "filters_applied": {
      "date_range": ["2024-12-01T00:00:00Z", "2024-12-10T23:59:59Z"],
      "page_id": null,
      "split_test_id": null
    }
  }
  ```
</ResponseExample>

***

## Get Grouped Metrics

Retrieve metrics grouped by a specific field (e.g., by product, page, affiliate).

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Grouping field: `product`, `page`, `aff_id`, `day`, `hour`, `country`, `device`, `utm_source`, etc.
</ParamField>

<ParamField type="string">
  Start date (ISO 8601 format)
</ParamField>

<ParamField type="string">
  End date (ISO 8601 format)
</ParamField>

<ParamField type="array">
  Array of metric keys to retrieve
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/analytics/metrics/{field}/data
```

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/analytics/metrics/product/data?start=2024-12-01T00:00:00Z&end=2024-12-10T23:59:59Z&selected_metrics[]=revenue&selected_metrics[]=sales" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "row_key": "PROD-001",
      "row_name": "Main Product",
      "revenue": {
        "value": 9875.00,
        "formatted_value": "$9,875.00"
      },
      "sales": {
        "value": 198,
        "formatted_value": "198"
      }
    },
    {
      "row_key": "PROD-002",
      "row_name": "Upsell Product",
      "revenue": {
        "value": 5875.00,
        "formatted_value": "$5,875.00"
      },
      "sales": {
        "value": 117,
        "formatted_value": "117"
      }
    }
  ]
  ```
</ResponseExample>

***

## Export Grouped Metrics

Export grouped metrics to CSV or Excel.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Grouping field
</ParamField>

<ParamField type="array">
  Array of metric keys to export
</ParamField>

<ParamField type="string">
  Export format: `csv` or `excel` (default: `csv`)
</ParamField>

<ParamField type="object">
  Date range object with start/end dates
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/analytics/metrics/{field}/export
```

```bash cURL theme={null}
curl -X POST "https://app.elasticfunnels.io/api/brands/{brand_id}/analytics/metrics/product/export" \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["revenue", "sales", "aov"],
    "format": "csv",
    "date_range": {
      "start": "2024-12-01",
      "end": "2024-12-10"
    }
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "message": "Export has been queued. You will receive an email when it's ready.",
    "status": "queued",
    "field": "product"
  }
  ```
</ResponseExample>

***

## Available Grouping Fields

<AccordionGroup>
  <Accordion title="Time & Date">
    * `hour` - Hour of day (0-23)
    * `day` - Calendar day
    * `week` - Week number
    * `month` - Month
    * `year` - Year
    * `hour_of_day` - Time grouping
  </Accordion>

  <Accordion title="Business">
    * `aff_id` - Affiliate (requires permission)
    * `subid` - Sub ID
    * `merchant_id` - Merchant
    * `page` - Landing page
    * `product` - Product
    * `funnel_id` - Funnel
  </Accordion>

  <Accordion title="Geography">
    * `country` - Visitor country
    * `region` - Visitor region
    * `shipping_country` - Shipping destination
    * `shipping_state` - Shipping state
  </Accordion>

  <Accordion title="Technology">
    * `device` - Device type (desktop/mobile/tablet)
    * `os` - Operating system
    * `browser` - Browser type
    * `screen_resolution` - Screen size
    * `language` - Browser language
  </Accordion>

  <Accordion title="Marketing">
    * `utm_source` - Traffic source
    * `utm_medium` - Marketing medium
    * `utm_campaign` - Campaign
    * `utm_term` - Keyword/term
    * `utm_content` - Ad content
    * `referrer` - Referring website
  </Accordion>
</AccordionGroup>

***

## Compound Grouping

You can group by multiple fields simultaneously using semicolon separation:

```bash theme={null}
GET /api/brands/{brand}/analytics/metrics/product;page/data
```

This groups metrics by both product AND page.

***

## Filtering

Apply filters using the `filter[field]` query parameter:

```bash theme={null}
# Filter by affiliate
GET /api/brands/{brand}/analytics/metrics/data?filter[aff_id]=123

# Filter by device
GET /api/brands/{brand}/analytics/metrics/data?filter[device]=mobile

# Filter by country
GET /api/brands/{brand}/analytics/metrics/data?filter[country]=US

# Multiple filters
GET /api/brands/{brand}/analytics/metrics/data?filter[device]=mobile&filter[country]=US
```

***

## Custom Metrics

You can create custom metrics using formulas:

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/analytics/metrics/data?start=2024-12-01T00:00:00Z&end=2024-12-10T23:59:59Z&selected_metrics[]=metric_0" \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": {
      "0": {
        "name": "Profit Margin",
        "formula": "($revenue - $cogs - $ad_spend) / $revenue * 100",
        "as": "pct"
      }
    }
  }'
```

Custom metric formulas support:

* Basic math operators: `+`, `-`, `*`, `/`, `()`
* Variables: `$metric_name` (e.g., `$revenue`, `$sales`)
* Format types: `currency`, `pct` (percentage), `time`, `number`

***

## Common Metrics

| Metric | Description | Module Required |
| - | - | - |
| `revenue` | Total revenue | conversions |
| `sales` | Number of orders | conversions |
| `aov` | Average order value | conversions |
| `conversion_rate` | Conversion percentage | conversions, tracking |
| `page_views` | Total page views | tracking |
| `sessions` | Unique sessions | tracking |
| `engagement_rate` | User engagement | tracking |
| `time_on_page` | Avg time on page | tracking |
| `ad_spend` | Advertising cost | integrations |
| `roas` | Return on ad spend | conversions, integrations |
| `cogs` | Cost of goods sold | conversions |
| `net_revenue` | Revenue minus costs | conversions |

***

## Notes

<Info>
  * All dates should be in ISO 8601 format
  * The system automatically compares current period with previous period of equal length
  * Some metrics require specific modules to be enabled
  * Permission-restricted metrics (like `aff_id`) require appropriate user permissions
  * Analytics storage may vary by brand configuration
</Info>

<Warning>
  When grouping by `aff_id`, ensure your API key's user has the `affiliates.view` permission
</Warning>

***

## UTM Performance

Break down conversions and revenue by a single UTM dimension across a date range.

```
GET /api/brands/{brand}/utm-performance/{type}
```

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  UTM dimension: `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`
</ParamField>

<ParamField type="string">
  Start date (ISO 8601)
</ParamField>

<ParamField type="string">
  End date (ISO 8601)
</ParamField>

<ParamField type="string">
  Timezone (e.g. `America/New_York`)
</ParamField>

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/utm-performance/utm_source?start=2024-12-01T00:00:00Z&end=2024-12-10T23:59:59Z" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  [
    { "utm_source": "facebook", "revenue": 9200.00, "sales": 184, "aov": 50.00, "conversion_rate": 0.038, "page_views": 4842 },
    { "utm_source": "google",   "revenue": 4100.00, "sales": 82,  "aov": 50.00, "conversion_rate": 0.041, "page_views": 2000 }
  ]
  ```
</ResponseExample>

***

## Specific Analytics Cards

Individual endpoints for specialised analytics data. All accept `start` and `end` (ISO 8601) query params.

### Time Before First Purchase

How long visitors waited before converting — useful for identifying checkout hesitation.

```
GET /api/brands/{brand}/analytics/metrics/time-before-first-purchase
```

<ResponseExample>
  ```json Response theme={null}
  {
    "buckets": [
      { "label": "< 1 min",   "count": 92,  "pct": 0.29 },
      { "label": "1–5 min",   "count": 118, "pct": 0.37 },
      { "label": "5–15 min",  "count": 64,  "pct": 0.20 },
      { "label": "15–60 min", "count": 30,  "pct": 0.10 },
      { "label": "> 1 hour",  "count": 11,  "pct": 0.04 }
    ],
    "median_seconds": 187,
    "sample_size": 315
  }
  ```
</ResponseExample>

### Add-to-Carts by Video Watch Time

Identifies at which point in a video visitors add to cart — use to find optimal CTA placement.

```
GET /api/brands/{brand}/analytics/metrics/add-to-carts-by-video-time
```

<ResponseExample>
  ```json Response theme={null}
  {
    "buckets": [
      { "video_pct": 0,   "atcs": 12 },
      { "video_pct": 25,  "atcs": 31 },
      { "video_pct": 50,  "atcs": 54 },
      { "video_pct": 75,  "atcs": 29 },
      { "video_pct": 100, "atcs": 8 }
    ]
  }
  ```
</ResponseExample>

### Customer Gender Distribution

```
GET /api/brands/{brand}/analytics/metrics/customer-gender
```

<ResponseExample>
  ```json Response theme={null}
  {
    "male":    { "count": 182, "pct": 0.58 },
    "female":  { "count": 121, "pct": 0.38 },
    "unknown": { "count": 12,  "pct": 0.04 }
  }
  ```
</ResponseExample>

### Video Completion by Gender

```
GET /api/brands/{brand}/analytics/metrics/video-completion-by-gender
```

<ResponseExample>
  ```json Response theme={null}
  {
    "male":   { "avg_completion_pct": 64, "sample": 182 },
    "female": { "avg_completion_pct": 71, "sample": 121 }
  }
  ```
</ResponseExample>

### Products by Pages

Conversion performance broken down by page → product pair.

```
GET /api/brands/{brand}/analytics/metrics/products-by-pages/data
GET /api/brands/{brand}/analytics/metrics/products-by-pages/summary
```

<ResponseExample>
  ```json data response theme={null}
  [
    {
      "page_id": 101, "page_title": "Nutra Landing",
      "product_id": 5, "product_title": "1 Bottle",
      "revenue": 4600.00, "sales": 92, "conversion_rate": 0.038
    }
  ]
  ```
</ResponseExample>

### Upsell Take Rate

```
GET /api/brands/{brand}/analytics/metrics/upsell-take-rate/summary
```

<ResponseExample>
  ```json Response theme={null}
  {
    "upsells": [
      { "product_id": 8, "product_title": "3-Bottle Bundle", "shown": 315, "taken": 87, "take_rate": 0.276, "revenue": 7830.00 }
    ]
  }
  ```
</ResponseExample>

### Units Sold

```
GET /api/brands/{brand}/analytics/metrics/units-sold/summary
```

<ResponseExample>
  ```json Response theme={null}
  {
    "total_units": 847,
    "by_product": [
      { "product_id": 5, "title": "1 Bottle",   "units": 315 },
      { "product_id": 6, "title": "3 Bottles",  "units": 532 }
    ]
  }
  ```
</ResponseExample>

***

## Report Builder

Build, save, and export custom cross-dimensional analytics reports.

### Generate Report

```
POST /api/brands/{brand}/analytics/reports/generate
```

<ParamField type="array">
  Dimension keys to group by (e.g. `["product", "utm_source"]`). See [grouping fields](#available-grouping-fields).
</ParamField>

<ParamField type="array">
  Metric keys (e.g. `["revenue", "sales", "conversion_rate"]`)
</ParamField>

<ParamField type="string">
  Start date (ISO 8601)
</ParamField>

<ParamField type="string">
  End date (ISO 8601)
</ParamField>

<ParamField type="object">
  Key-value filters (e.g. `{"device": "mobile", "country": "US"}`)
</ParamField>

<ParamField type="number">
  Max rows returned (default: 100)
</ParamField>

```bash cURL theme={null}
curl -X POST "https://app.elasticfunnels.io/api/brands/{brand_id}/analytics/reports/generate" \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "group_by": ["utm_source", "product"],
    "metrics": ["revenue", "sales", "conversion_rate"],
    "start": "2024-12-01T00:00:00Z",
    "end": "2024-12-10T23:59:59Z",
    "filters": {"device": "mobile"},
    "limit": 50
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "rows": [
      {
        "utm_source": "facebook",
        "product": "1 Bottle",
        "revenue": { "value": 4600.00, "formatted_value": "$4,600.00" },
        "sales": { "value": 92, "formatted_value": "92" },
        "conversion_rate": { "value": 0.038, "formatted_value": "3.8%" }
      }
    ],
    "total_rows": 14,
    "truncated": false
  }
  ```
</ResponseExample>

### Get Available Grouping Fields (Report Builder)

```
GET /api/brands/{brand}/analytics/reports/grouping-fields
```

### Get Reporting Periods

```
GET /api/brands/{brand}/analytics/reports/reporting-periods
```

Returns available pre-set periods: `today`, `yesterday`, `last_7_days`, `last_30_days`, `this_month`, `last_month`, etc.

### Save Report

```
POST /api/brands/{brand}/analytics/reports/save
```

<ParamField type="string">
  Report name
</ParamField>

<ParamField type="object">
  Same body as `generate` — stored and re-runnable on demand.
</ParamField>

### List Saved Reports

```
GET /api/brands/{brand}/analytics/reports/saved
```

### Load Saved Report

```
GET /api/brands/{brand}/analytics/reports/saved/{reportId}
```

### Export Saved Report

```
POST /api/brands/{brand}/analytics/reports/saved/{reportId}/export
```

### Delete Saved Report

```
DELETE /api/brands/{brand}/analytics/reports/saved/{reportId}
```

### Export Current Report

```
POST /api/brands/{brand}/analytics/reports/export
```

<ParamField type="string">
  `csv` (default) or `excel`
</ParamField>

Other body fields same as Generate. Queues an export job and emails a download link when complete.

<ResponseExample>
  ```json 200 Queued theme={null}
  {
    "message": "Export has been queued. You will receive an email when it's ready.",
    "status": "queued"
  }
  ```
</ResponseExample>

***

## Analytics Segments

Create and manage reusable audience segments for filtering reports.

### List Segments

```
GET /api/brands/{brand}/analytics/segments
```

### Get Segment

```
GET /api/brands/{brand}/analytics/segments/{segment}
```

### Create Segment

```
POST /api/brands/{brand}/analytics/segments
```

<ParamField type="string">
  Segment name
</ParamField>

<ParamField type="array">
  Array of condition objects. Each has `field`, `operator` (`eq`, `neq`, `gte`, `lte`, `in`), and `value`.
</ParamField>

<ParamField type="string">
  How conditions combine: `and` (default) or `or`
</ParamField>

```bash cURL theme={null}
curl -X POST "https://app.elasticfunnels.io/api/brands/{brand_id}/analytics/segments" \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High-Value Mobile Buyers",
    "operator": "and",
    "conditions": [
      { "field": "device",  "operator": "eq",  "value": "mobile" },
      { "field": "revenue", "operator": "gte", "value": 100 }
    ]
  }'
```

<ResponseExample>
  ```json 200 Created theme={null}
  {
    "id": 4,
    "name": "High-Value Mobile Buyers",
    "operator": "and",
    "conditions": [
      { "field": "device",  "operator": "eq",  "value": "mobile" },
      { "field": "revenue", "operator": "gte", "value": 100 }
    ],
    "brand_id": 42,
    "created_at": "2024-12-11T09:00:00.000000Z"
  }
  ```
</ResponseExample>

### Update Segment

```
PUT /api/brands/{brand}/analytics/segments/{segment}
```

### Delete Segment

```
DELETE /api/brands/{brand}/analytics/segments/{segment}
```

### Preview Segment

Run a segment definition against live data without saving it.

```
POST /api/brands/{brand}/analytics/segments/preview
```

Body: same as Create.

<ResponseExample>
  ```json Preview response theme={null}
  {
    "count": 487,
    "sample": [
      { "session_id": "abc123", "revenue": 147.00, "device": "mobile" }
    ]
  }
  ```
</ResponseExample>

### Install Default Segments

```
POST /api/brands/{brand}/analytics/segments/install-defaults
```

Installs a curated starter set (e.g. "New Buyers", "Repeat Customers", "Abandoned Carts").


# Automations
Source: https://docs.elasticfunnels.io/api-reference/endpoints/automations

Create and manage automation workflows, read execution stats, and manage builder configs

<Note>
  All Automations endpoints sit under `/api/brands/{brand}/automations/` with `moduleAccess:automations` middleware. Authenticate with `EF-Access-Key`.
</Note>

***

## List Automations

```
GET /api/brands/{brand}/automations
```

<ParamField type="number">
  Results per page (1–100, default: 25)
</ParamField>

<ParamField type="string">
  Search by title
</ParamField>

<ParamField type="string">
  `newest` (default), `oldest`, `created_at`, `updated_at`
</ParamField>

<ParamField type="string">
  `asc` or `desc` (used with `created_at` / `updated_at`)
</ParamField>

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/automations?q=welcome&per_page=50" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "current_page": 1,
    "data": [
      {
        "id": 12,
        "title": "Welcome Email Sequence",
        "status": "active",
        "trigger_node_type": "form_submission",
        "entry_node": "start",
        "postback_code": "abc-123",
        "collection_code": "lead-capture",
        "created_at": "2024-12-01T10:00:00.000000Z",
        "updated_at": "2024-12-10T15:00:00.000000Z"
      }
    ],
    "per_page": 25,
    "total": 8,
    "last_page": 1
  }
  ```
</ResponseExample>

***

## List Automations (Unpaginated)

```
GET /api/brands/{brand}/automations/all
```

Returns `{ id, title }` for all automations — useful for dropdowns.

<ResponseExample>
  ```json Response theme={null}
  [
    { "id": 12, "title": "Welcome Email Sequence" },
    { "id": 15, "title": "Abandoned Cart Recovery" }
  ]
  ```
</ResponseExample>

***

## Get Automation

```
GET /api/brands/{brand}/automations/{automation}
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 12,
    "title": "Welcome Email Sequence",
    "postback_code": "abc-123",
    "trigger_node_type": "form_submission"
  }
  ```
</ResponseExample>

***

## Create Automation

```
POST /api/brands/{brand}/automations
```

<ParamField type="string">
  Automation name (max 255 chars)
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/automations \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"title": "Post-Purchase Upsell"}'
```

<ResponseExample>
  ```json 200 Created theme={null}
  {
    "automation": {
      "id": 16,
      "title": "Post-Purchase Upsell",
      "status": "draft",
      "brand_id": 42,
      "created_at": "2024-12-11T10:00:00.000000Z"
    }
  }
  ```

  ```json 403 Plan limit theme={null}
  {
    "error": "Upgrade required to create automations",
    "plan_error": {
      "message": "Your current plan does not allow creating automations.",
      "upgrade_info": {}
    }
  }
  ```
</ResponseExample>

***

## Update Automation

```
PUT /api/brands/{brand}/automations/{automation}
```

<ParamField type="string">
  New title (max 255)
</ParamField>

<ParamField type="string">
  `active`, `inactive`, or `draft`
</ParamField>

<ParamField type="string">
  Trigger type (e.g. `form_submission`, `purchase`, `tag_added`)
</ParamField>

<ParamField type="string">
  Entry node code
</ParamField>

<ParamField type="string">
  Custom postback code (max 255)
</ParamField>

<ParamField type="string">
  Collection code to attach
</ParamField>

***

## Delete Automation

```
DELETE /api/brands/{brand}/automations/{automation}
```

<ResponseExample>
  ```json Response theme={null}
  { "success": true }
  ```
</ResponseExample>

***

## Clone Automation

Creates a full copy of an automation within the same brand.

```
POST /api/brands/{brand}/automations/{automation}/clone
```

<ParamField type="string">
  New name for the clone. Defaults to `"<original title> (Copy)"`.
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/automations/12/clone \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"title": "Welcome Sequence v2"}'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "automation": {
      "id": 17,
      "title": "Welcome Sequence v2",
      "status": "draft"
    }
  }
  ```
</ResponseExample>

***

## Copy Automation to Another Brand

```
POST /api/brands/{brand}/automations/copy
```

<ParamField type="number">
  Source automation ID
</ParamField>

<ParamField type="number">
  Target brand ID to copy into
</ParamField>

<ParamField type="string">
  Title for the copied automation in the target brand
</ParamField>

<ResponseExample>
  ```json 200 Copied theme={null}
  {
    "automation_id": 23
  }
  ```

  ```json 404 Not found theme={null}
  {
    "error": "Automation not found."
  }
  ```
</ResponseExample>

***

## Export Automations

Queue a CSV export of automation records.

```
POST /api/brands/{brand}/automations/export
```

<ParamField type="array">
  Filter conditions
</ParamField>

<ParamField type="array">
  Limit export to specific automation IDs
</ParamField>

<ParamField type="array">
  Columns to include
</ParamField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "message": "Export started. You will receive an email when it is ready."
  }
  ```
</ResponseExample>

***

## Get Builder Config

Returns the full visual-builder JSON for an automation. If a draft revision exists, the draft is returned instead of the published version.

```
GET /api/brands/{brand}/automations/{automation}/builder
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/automations/12/builder \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 12,
    "title": "Welcome Email Sequence",
    "config": {
      "nodes": { /* builder nodes */ },
      "connections": { /* node connections */ }
    },
    "version": 3,
    "trigger_node_type": "form_submission"
  }
  ```

  ```
  200 (empty string)  — automation exists but has no builder config yet
  ```
</ResponseExample>

***

## Save Builder Config

Saves the visual-builder JSON. Pass `draft=true` to save as a draft revision without publishing.

```
POST /api/brands/{brand}/automations/{automation}/builder
```

<ParamField type="object">
  The complete builder config object (same shape as returned by GET)
</ParamField>

<ParamField type="boolean">
  If `true`, saves as a draft revision. Published configs are deployed to S3 and activate the automation.
</ParamField>

```bash cURL — save as draft theme={null}
curl -X POST "https://app.elasticfunnels.io/api/brands/{brand_id}/automations/12/builder?draft=true" \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ /* builder JSON */ }'
```

***

## Discard Draft Revision

Discards the current draft revision and reverts to the last published version.

```
POST /api/brands/{brand}/automations/{automation}/discard-revision
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 12,
    "title": "Welcome Email Sequence",
    "config": { /* last published config */ }
  }
  ```
</ResponseExample>

***

## Get Automation Stats

Returns execution counts per node, aggregated from the event log.

```
GET /api/brands/{brand}/automations/{automation}/stats
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/automations/12/stats \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "start-node-abc": {
      "success": 315,
      "failed": 2,
      "skipped": 5
    },
    "send-email-def": {
      "success": 308,
      "failed": 9
    }
  }
  ```
</ResponseExample>

***

## Execution Summary

Global summary of automation runs for the brand.

```
GET /api/brands/{brand}/automations/summary
```

<ResponseExample>
  ```json Response theme={null}
  {
    "total_runs": 1420,
    "successful_tasks": 1387,
    "failed_tasks": 33,
    "task_status_counts": {
      "success": 1387,
      "failed": 33
    },
    "period_start_date": "2024-12-01T00:00:00Z",
    "period_end_date": "2024-12-31T23:59:59Z"
  }
  ```
</ResponseExample>

***

## Execution Summary by Automation

```
GET /api/brands/{brand}/automations/summary-by-automation
```

Returns execution stats grouped per automation ID.

***

## Automation Event Log

```
GET /api/brands/{brand}/automations/{automation}/logs
```

Returns paginated execution log for a specific automation.

***

## Automation Events

```
GET /api/brands/{brand}/automations/{automation}/events
```

Returns available event types that have fired for this automation.

***

## Notes

<Info>
  * `postback_code` is the unique trigger code used in postback URLs (`/webhooks/{code}`)
  * Builder configs are deployed to S3 on publish — **draft saves do not activate** the automation
  * Stats are read from Elasticsearch and may have a short indexing delay
  * The `copy` endpoint copies across brands; `clone` copies within the same brand
</Info>


# Blogs
Source: https://docs.elasticfunnels.io/api-reference/endpoints/blogs

Manage blogs, articles, and blog categories

<Note>
  Blog endpoints sit under `/api/brands/{brand}/blogs/` with `brandAccess` middleware. Authenticate with `EF-Access-Key`.
</Note>

***

## List Blogs

```
GET /api/brands/{brand}/blogs
```

<ParamField type="number">
  Results per page (1–100, default: 25)
</ParamField>

<ParamField type="string">
  Search by name
</ParamField>

<ParamField type="string">
  `newest`, `oldest`, `created_at`, `updated_at`
</ParamField>

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/blogs \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "current_page": 1,
    "data": [
      {
        "id": 2,
        "name": "Health Tips Blog",
        "slug": "health-tips",
        "domain_id": 7,
        "status": "published",
        "comments_enabled": false,
        "article_url_pattern": "slug_only",
        "created_at": "2024-10-01T00:00:00.000000Z"
      }
    ],
    "per_page": 25,
    "total": 2,
    "last_page": 1
  }
  ```
</ResponseExample>

***

## List Blogs (Unpaginated)

```
GET /api/brands/{brand}/blogs/all
```

Returns `{ id, name }` for all blogs with a saved config — useful for dropdowns.

***

## Get Blog

```
GET /api/brands/{brand}/blogs/{blog}
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 2,
    "name": "Health Tips Blog",
    "domain_id": 7,
    "brand_template_id": null,
    "slug": "health-tips",
    "article_url_pattern": "slug_only",
    "article_url_segment": null,
    "category_url_segment": "category",
    "tag_url_segment": "tag",
    "search_url_segment": "search",
    "comments_enabled": false,
    "comments_require_email_confirmation": false,
    "seo_settings": [],
    "template": null
  }
  ```
</ResponseExample>

***

## Create Blog

```
POST /api/brands/{brand}/blogs
```

<ParamField type="string">
  Blog name
</ParamField>

<ParamField type="number">
  ID of the domain this blog lives on
</ParamField>

<ParamField type="string">
  URL slug (kebab-case, max 255). Must be unique per brand + domain.
</ParamField>

<ParamField type="number">
  ID of the template to apply (`context=blog`)
</ParamField>

<ParamField type="string">
  `slug_only`, `segment`, or `category`
</ParamField>

<ParamField type="string">
  URL prefix for articles (max 64)
</ParamField>

<ParamField type="string">
  URL prefix for category pages (default: `category`, max 64)
</ParamField>

<ParamField type="string">
  URL prefix for tag pages (default: `tag`, max 64)
</ParamField>

<ParamField type="string">
  URL prefix for search results (default: `search`, max 64)
</ParamField>

<ParamField type="boolean">
  Enable comment system for articles
</ParamField>

<ParamField type="boolean">
  Require email confirmation before comments appear
</ParamField>

<ParamField type="object">
  SEO metadata object (meta title, description, OG tags, Twitter card fields)
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/blogs \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Health Tips Blog",
    "domain_id": 7,
    "slug": "health-tips",
    "article_url_pattern": "slug_only"
  }'
```

<ResponseExample>
  ```json 200 Created theme={null}
  {
    "blog": {
      "id": 2,
      "name": "Health Tips Blog",
      "slug": "health-tips",
      "domain_id": 7,
      "comments_enabled": false,
      "brand_id": 42,
      "created_at": "2024-12-11T10:00:00.000000Z"
    }
  }
  ```

  ```json 422 Missing name theme={null}
  {
    "errors": {
      "name": ["The name field is required."]
    }
  }
  ```

  ```json 422 Duplicate slug theme={null}
  {
    "errors": {
      "slug": ["The slug has already been taken."]
    }
  }
  ```
</ResponseExample>

<Warning>
  `name` is **always required** — even on `PUT`/`PATCH` updates. A partial update that omits `name` will return a 422 validation error.
</Warning>

***

## Update Blog

```
PUT /api/brands/{brand}/blogs/{blog}
```

Same body as Create. `name` is still required.

***

## Delete Blog

```
DELETE /api/brands/{brand}/blogs/{blog}
```

<ResponseExample>
  ```json Response theme={null}
  { "blog": { /* soft-deleted blog object */ } }
  ```
</ResponseExample>

***

## Clone Blog

Creates a copy of a blog within the same brand.

```
POST /api/brands/{brand}/blogs/{blog}/clone
```

<ParamField type="string">
  Name for the cloned blog (max 255). Defaults to `"<original name> (Copy)"` if omitted.
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/blogs/2/clone \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"title": "Health Tips Blog v2"}'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 3,
    "blog": { /* cloned BrandBlog model */ }
  }
  ```
</ResponseExample>

***

## Export Blogs

```
POST /api/brands/{brand}/blogs/export
```

<ParamField type="array">
  Filter conditions (same as list query params)
</ParamField>

<ParamField type="array">
  Limit export to specific blog IDs
</ParamField>

<ParamField type="array">
  Columns to include
</ParamField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "message": "Export started. You will receive an email when it is ready."
  }
  ```
</ResponseExample>

***

## Blog Categories

### List Categories

```
GET /api/brands/{brand}/blogs/{blog}/categories
```

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "id": 1,
      "blog_id": 2,
      "name": "Nutrition",
      "slug": "nutrition",
      "hero_image": null,
      "seo_settings": {}
    }
  ]
  ```
</ResponseExample>

### Create Category

```
POST /api/brands/{brand}/blogs/{blog}/categories
```

<ParamField type="string">
  Category name (max 255)
</ParamField>

<ParamField type="string">
  URL slug. Auto-generated from `name` if omitted; appends numeric suffix on collision.
</ParamField>

<ParamField type="string">
  Image URL (max 2048 chars)
</ParamField>

<ParamField type="object">
  SEO metadata (meta title, description, OG tags, Twitter card)
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/blogs/2/categories \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Nutrition", "slug": "nutrition"}'
```

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": 1,
    "blog_id": 2,
    "name": "Nutrition",
    "slug": "nutrition"
  }
  ```
</ResponseExample>

### Update Category

```
PUT /api/brands/{brand}/blogs/{blog}/categories/{category}
```

Same body as Create (all fields optional on update).

### Delete Category

```
DELETE /api/brands/{brand}/blogs/{blog}/categories/{category}
```

<ResponseExample>
  ```json Response theme={null}
  { "deleted": true }
  ```
</ResponseExample>

***

## Notes

<Info>
  * Blog slugs must be globally unique per `brand_id` + `domain_id` combination
  * The `clone` endpoint copies the blog's `config`, `html`, `css`, and `interactions` to the new blog. Slug uniqueness is handled automatically with a numeric suffix
  * The builder (`GET/POST .../blogs/{blog}/builder`) and articles CRUD endpoints are managed through the page builder and article editor controllers respectively
</Info>


# Brands (Projects)
Source: https://docs.elasticfunnels.io/api-reference/endpoints/brands

Manage your projects and retrieve project information

## Get Brand Details

Retrieve details about a specific project (brand).

<ParamField type="string">
  The brand/project ID
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id} \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 123,
    "name": "My Awesome Funnel",
    "subdomain": "myawesomefunnel",
    "timezone": "America/New_York",
    "currency": "USD",
    "subscription_status": "active",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-12-10T08:20:00.000000Z"
  }
  ```
</ResponseExample>

***

## List All Brands

Get a list of all projects you have access to.

```bash Request theme={null}
GET /api/brands/all
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/all \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": 123,
        "name": "My Awesome Funnel",
        "subdomain": "myawesomefunnel",
        "subscription_status": "active"
      },
      {
        "id": 456,
        "name": "Another Project",
        "subdomain": "anotherproject",
        "subscription_status": "active"
      }
    ]
  }
  ```
</ResponseExample>

***

## Update Brand

Update project settings (requires admin/owner permissions).

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Project name
</ParamField>

<ParamField type="string">
  Project timezone (e.g., "America/New\_York")
</ParamField>

<ParamField type="string">
  Currency code (e.g., "USD", "EUR")
</ParamField>

```bash Request theme={null}
PUT /api/brands/{brand}
```

```bash cURL theme={null}
curl -X PUT https://app.elasticfunnels.io/api/brands/{brand_id} \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Project Name",
    "timezone": "America/Los_Angeles"
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 123,
    "name": "Updated Project Name",
    "subdomain": "myawesomefunnel",
    "timezone": "America/Los_Angeles",
    "currency": "USD",
    "subscription_status": "active",
    "updated_at": "2024-12-10T15:45:00.000000Z"
  }
  ```
</ResponseExample>

***

## Get Brand Metrics

Retrieve configured metrics for the project.

<ParamField type="string">
  The brand/project ID
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/metrics
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/metrics \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "metrics": [
      "orders",
      "revenue",
      "aov",
      "conversion_rate",
      "roas"
    ]
  }
  ```
</ResponseExample>


# Collections
Source: https://docs.elasticfunnels.io/api-reference/endpoints/collections

Manage form collections (schemas) and their entries

<Note>
  All Collections endpoints sit under `/api/brands/{brand}/collections/` with `moduleAccess:collections` middleware. Authenticate with `EF-Access-Key`.
</Note>

Collections are dynamic form schemas. Each collection has a set of typed **fields**, and every form submission creates an **entry** validated against that schema.

***

## List Collections

```
GET /api/brands/{brand}/collections
```

<ParamField type="number">
  Results per page (1–100, default: 25)
</ParamField>

<ParamField type="string">
  Search by name or code
</ParamField>

<ParamField type="string">
  `newest` (default), `oldest`, `created_at`, `updated_at`
</ParamField>

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/collections \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "current_page": 1,
    "data": [
      {
        "id": 3,
        "code": "contact-form",
        "name": "Contact Form",
        "public_export": false,
        "total_entries": 142
      }
    ],
    "per_page": 25,
    "total": 3,
    "last_page": 1
  }
  ```
</ResponseExample>

***

## List Collections (Unpaginated)

Returns `id`, `name`, `code` only — useful for dropdowns.

```
GET /api/brands/{brand}/collections/all
```

<ResponseExample>
  ```json Response theme={null}
  [
    { "id": 3, "name": "Contact Form", "code": "contact-form" },
    { "id": 4, "name": "Lead Capture", "code": "lead-capture" }
  ]
  ```
</ResponseExample>

***

## Get Collection

Returns the full collection schema including all field definitions.

```
GET /api/brands/{brand}/collections/{collection}
```

<ParamField type="string">
  Collection numeric ID **or** `code` slug
</ParamField>

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/collections/contact-form \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 3,
    "code": "contact-form",
    "name": "Contact Form",
    "public_export": false,
    "total_entries": 142,
    "on_new_entry": "send_admin_email",
    "send_to_email": "admin@example.com",
    "recaptcha_enabled": false,
    "recaptcha_site_key": null,
    "recaptcha_secret_key": null,
    "ticket_source_id": null,
    "fields": [
      {
        "id": 1,
        "code": "full_name",
        "name": "Full Name",
        "type": "text",
        "placeholder": "Enter your name",
        "options": null,
        "required": true,
        "searchable": true,
        "private": false,
        "public_encrypt": false,
        "public_exclude": false,
        "order": 0,
        "default_value": null
      },
      {
        "id": 2,
        "code": "email",
        "name": "Email",
        "type": "email",
        "placeholder": "you@example.com",
        "required": true,
        "order": 1
      }
    ]
  }
  ```
</ResponseExample>

***

## Get Collection Fields

```
GET /api/brands/{brand}/collections/{collection}/fields
```

Returns the raw field list for a collection (numeric ID only for this route).

***

## Create Collection

```
POST /api/brands/{brand}/collections
```

<ParamField type="string">
  Collection name (max 255 chars)
</ParamField>

<ParamField type="array">
  Array of field definition objects (at least one)
</ParamField>

<ParamField type="string">
  Field label (max 255)
</ParamField>

<ParamField type="string">
  `text`, `email`, `number`, `checkbox`, `password`, `textarea`, `select`, or `hidden`
</ParamField>

<ParamField type="boolean">
  Whether the field is required on submission
</ParamField>

<ParamField type="string">
  Input placeholder (max 255)
</ParamField>

<ParamField type="array">
  Required when `type` is `select` — array of option strings (at least one)
</ParamField>

<ParamField type="string">
  Default value for the field (max 255)
</ParamField>

<ParamField type="number">
  Display order (integer, min 0)
</ParamField>

<ParamField type="boolean">
  Whether entries can be searched by this field
</ParamField>

<ParamField type="boolean">
  Hide field from public-facing builder views
</ParamField>

<ParamField type="boolean">
  Allow public CSV download of entries
</ParamField>

<ParamField type="string">
  `send_admin_email`, `send_email_to`, or `create_new_ticket`
</ParamField>

<ParamField type="string">
  Required when `on_new_entry` is `send_email_to`. Valid email address.
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/collections \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lead Capture",
    "on_new_entry": "send_admin_email",
    "fields": [
      { "name": "Full Name", "type": "text",  "required": true,  "order": 0 },
      { "name": "Email",     "type": "email", "required": true,  "order": 1 },
      { "name": "Source",    "type": "select","required": false, "order": 2,
        "options": ["Facebook", "Google", "Organic"] }
    ]
  }'
```

<ResponseExample>
  ```json 200 Created theme={null}
  {
    "id": 5,
    "code": "lead-capture",
    "name": "Lead Capture",
    "total_entries": 0,
    "fields": [ /* ... */ ]
  }
  ```

  ```json 422 Missing required field name theme={null}
  {
    "errors": {
      "fields.0.name": ["Field name is required."],
      "fields.0.type": ["Field type is required."]
    }
  }
  ```

  ```json 422 Select missing options theme={null}
  {
    "errors": {
      "fields.2.options": ["You must provide at least one option for select fields."]
    }
  }
  ```
</ResponseExample>

***

## Update Collection

```
PUT /api/brands/{brand}/collections/{collection}
```

<ParamField type="number">
  Collection numeric ID
</ParamField>

Same body as Create. To update an existing field, include its `id`; to delete a field, pass `"deleted": true` on the field object.

***

## Delete Collection

```
DELETE /api/brands/{brand}/collections/{collection}
```

<ResponseExample>
  ```json Response theme={null}
  { "success": true }
  ```
</ResponseExample>

***

## List Entries

```
GET /api/brands/{brand}/collections/{collection}/entries
```

<ParamField type="number">
  Collection numeric ID
</ParamField>

<ParamField type="number">
  Results per page (default: 30)
</ParamField>

<ParamField type="string">
  Search entry titles
</ParamField>

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/collections/3/entries?per_page=50" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": "es-doc-abc123",
        "title": "Jane Doe",
        "full_name": "Jane Doe",
        "email": "jane@example.com",
        "source": "Facebook",
        "created_at": "2024-12-10T09:00:00Z",
        "updated_at": "2024-12-10T09:00:00Z"
      }
    ],
    "current_page": 1,
    "total": 142
  }
  ```
</ResponseExample>

***

## Get Entry

```
GET /api/brands/{brand}/collections/{collection}/entries/{entry}
```

Returns a single entry with all field values flattened to top-level keys.

***

## Create Entry

```
POST /api/brands/{brand}/collections/{collection}/entries
```

<Warning>
  The request body is validated **dynamically** against the collection's field schema. Field codes (e.g. `email`, `full_name`) become the body keys. Required fields and type rules are enforced per field definition.
</Warning>

<ParamField type="string | number | boolean">
  One key per collection field, using the field's `code` as the key. Type rules: `email` → valid email, `number` → numeric, `checkbox` → boolean, `select` → must be one of the defined options, all others → string.
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/collections/3/entries \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Jane Doe",
    "email": "jane@example.com",
    "source": "Facebook"
  }'
```

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "message": "Entry created successfully",
    "data": {
      "full_name": "Jane Doe",
      "email": "jane@example.com",
      "source": "Facebook"
    },
    "id": "es-doc-abc123"
  }
  ```

  ```json 422 Invalid field value theme={null}
  {
    "errors": {
      "email": ["The email must be a valid email address."],
      "source": ["The selected source is invalid."]
    }
  }
  ```
</ResponseExample>

***

## Update Entry

```
PUT /api/brands/{brand}/collections/{collection}/entries/{entry}
```

Same body as Create — only provided fields are merged into the existing entry.

***

## Delete Entry

```
DELETE /api/brands/{brand}/collections/{collection}/entries/{entry}
```

***

## Bulk Delete Entries

```
DELETE /api/brands/{brand}/collections/{collection}/entries/bulk-delete
```

<ParamField type="array">
  Array of entry IDs to delete
</ParamField>

***

## Export Entries

Queue a CSV export of all entries in a collection. The results are emailed to the specified address.

```
POST /api/brands/{brand}/collections/{collection}/export
```

<ParamField type="string">
  Email address to send the export to
</ParamField>

<ParamField type="array">
  Array of field codes to include in the export
</ParamField>

<ParamField type="boolean">
  Export only new entries since last export
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/collections/3/export \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "fields": ["full_name", "email", "source"]}'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "message": "Export started. You will receive an email when it is ready."
  }
  ```
</ResponseExample>


# Components
Source: https://docs.elasticfunnels.io/api-reference/endpoints/components

Create, read, update, and delete reusable page components via API

<Note>
  All component endpoints authenticate via `EF-Access-Key`. The brand user's role must have `components` module access.
</Note>

***

## List Components

Return all components for a brand with pagination. This endpoint does not include `html`, `css`, or `config` in the response — use [Get Component Content](#get-component-content) or [Get Component Builder Config](#get-component-builder-config) for full content.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="number">
  Results per page (1–100, default: 25)
</ParamField>

<ParamField type="number">
  Page number (default: 1)
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/components
```

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/components?per_page=100" \
  -H "EF-Access-Key: your_api_key_here"
```

```javascript JavaScript theme={null}
const res = await fetch(
  'https://app.elasticfunnels.io/api/brands/{brand_id}/components',
  { headers: { 'EF-Access-Key': 'your_api_key_here' } }
);
const { data, total, current_page, last_page } = await res.json();
```

<ResponseExample>
  ```json Response theme={null}
  {
    "current_page": 1,
    "data": [
      {
        "id": 12,
        "name": "Hero Section",
        "code": "custom-hero-section",
        "type": "editor",
        "screenshot": null,
        "brand_id": 42,
        "created_at": "2024-11-01T09:00:00.000000Z",
        "updated_at": "2024-12-10T14:30:00.000000Z",
        "tags": []
      },
      {
        "id": 13,
        "name": "Guarantee Badge",
        "code": "custom-guarantee-badge",
        "type": null,
        "screenshot": null,
        "brand_id": 42,
        "created_at": "2024-11-05T10:00:00.000000Z",
        "updated_at": "2024-11-05T10:00:00.000000Z",
        "tags": []
      }
    ],
    "per_page": 25,
    "total": 2,
    "last_page": 1,
    "from": 1,
    "to": 2
  }
  ```
</ResponseExample>

***

## Get All Components (unpaginated)

Return all components for a brand in a single array, without pagination (no `builder config` filter is applied).

<Note>
  This endpoint returns a lightweight shape: `id`, `name`, `code`, `type`, `screenshot`, and (unless `?short=true`) `config`. It does **not** return `html` or `css`. For HTML use [Get Component Content](#get-component-content); for GrapesJS config use [Get Component Builder Config](#get-component-builder-config).
</Note>

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Filter by type. Pass `editor` to return only visual-builder components.
</ParamField>

<ParamField type="boolean">
  When `true`, omits `config` from the response — returns only `id`, `name`, `code`, `type`, and `screenshot`. Useful for lightweight dropdowns.
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/components/all
```

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/components/all" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "id": 12,
      "name": "Hero Section",
      "code": "custom-hero-section",
      "type": "editor",
      "config": { "data": { "type": "wrapper", "components": [] }, "styles": [] },
      "screenshot": null
    }
  ]
  ```
</ResponseExample>

***

## Get Component

Retrieve a single component's **metadata** (not full content). Accepts either a numeric ID or the component's `code` string.

<Warning>
  This endpoint returns only `id`, `name`, `code`, and `screenshot`. It does **not** include `html`, `css`, `config`, `type`, or timestamps. Use the content endpoints below for body data.
</Warning>

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Numeric ID **or** `code` string (e.g. `custom-hero-section`)
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/components/{component}
```

```bash cURL (by ID) theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/components/12 \
  -H "EF-Access-Key: your_api_key_here"
```

```bash cURL (by code) theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/components/custom-hero-section \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 12,
    "name": "Hero Section",
    "code": "custom-hero-section",
    "screenshot": null
  }
  ```

  ```json 404 Not found theme={null}
  {
    "message": "No query results for model [BrandPageComponent]."
  }
  ```
</ResponseExample>

***

## Create Component

Create a new reusable component. This is the only endpoint that accepts `html`, `css`, and `config` — [Update Component](#update-component) is metadata-only.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Display name shown in the component library
</ParamField>

<ParamField type="string">
  Unique identifier used to embed the component in pages (e.g. `custom-guarantee-badge`). Auto-generated if omitted. Components are automatically prefixed with `custom-`.
</ParamField>

<ParamField type="string">
  HTML markup for the component
</ParamField>

<ParamField type="string">
  CSS styles scoped to this component
</ParamField>

<ParamField type="object">
  Builder config object. Required for visual-builder components; omit for plain HTML components.
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/components
```

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/components \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Guarantee Badge",
    "code": "custom-guarantee-badge",
    "html": "<div class=\"badge\"><img src=\"https://cdn.elasticfunnels.io/42/assets/media/guarantee-badge.png\" alt=\"60-Day Guarantee\"></div>",
    "css": ".badge { max-width: 200px; margin: 20px auto; text-align: center; }"
  }'
```

```python Python theme={null}
import requests

r = requests.post(
    'https://app.elasticfunnels.io/api/brands/{brand_id}/components',
    headers={'EF-Access-Key': 'your_api_key_here', 'Content-Type': 'application/json'},
    json={
        'name': 'Guarantee Badge',
        'code': 'custom-guarantee-badge',
        'html': '<div class="badge">...</div>',
        'css': '.badge { max-width: 200px; }',
    },
)
component = r.json()['pageComponent']
print(component['id'], component['code'])
```

```javascript JavaScript theme={null}
const res = await fetch(
  'https://app.elasticfunnels.io/api/brands/{brand_id}/components',
  {
    method: 'POST',
    headers: {
      'EF-Access-Key': 'your_api_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Guarantee Badge',
      code: 'custom-guarantee-badge',
      html: '<div class="badge">...</div>',
      css: '.badge { max-width: 200px; }',
    }),
  }
);
const { pageComponent } = await res.json();
```

<ResponseExample>
  ```json 200 Created theme={null}
  {
    "pageComponent": {
      "id": 14,
      "name": "Guarantee Badge",
      "code": "custom-guarantee-badge",
      "type": null,
      "html": "<div class=\"badge\">...</div>",
      "css": ".badge { max-width: 200px; margin: 20px auto; text-align: center; }",
      "brand_id": 42,
      "created_at": "2024-12-10T16:00:00.000000Z",
      "updated_at": "2024-12-10T16:00:00.000000Z"
    }
  }
  ```

  ```json 422 Validation error theme={null}
  {
    "errors": {
      "name": ["The name field is required."]
    }
  }
  ```
</ResponseExample>

***

## Update Component

Update a component's **metadata only** — name and code slug. This endpoint does **not** accept or persist `html`, `css`, or `config`. To update a component's HTML content use [Update Component Content](#update-component-content). To replace a component entirely, delete it and re-create it with [Create Component](#create-component).

<Warning>
  **`html`, `css`, and `config` are silently ignored on PUT.** The endpoint returns `200` even if you include them — but the content is not saved.
</Warning>

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Numeric ID **or** `code` string
</ParamField>

<ParamField type="string">
  Display name. **Required even if you are not changing it** — send the current name.
</ParamField>

<ParamField type="string">
  Rename the component's code slug. If changed, **all pages that reference this component are automatically updated** to use the new code.
</ParamField>

```bash Request theme={null}
PUT /api/brands/{brand}/components/{component}
```

```bash cURL (rename code) theme={null}
curl -X PUT https://app.elasticfunnels.io/api/brands/{brand_id}/components/14 \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Guarantee Badge",
    "code": "custom-guarantee-v2"
  }'
```

```bash cURL (rename by current code) theme={null}
curl -X PUT https://app.elasticfunnels.io/api/brands/{brand_id}/components/custom-guarantee-badge \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Guarantee Badge v2"
  }'
```

<ResponseExample>
  ```json 200 Updated theme={null}
  {
    "id": 14,
    "name": "Guarantee Badge v2",
    "code": "custom-guarantee-badge",
    "type": null,
    "brand_id": 42,
    "updated_at": "2024-12-11T09:15:00.000000Z"
  }
  ```

  ```json 422 Missing required name theme={null}
  {
    "errors": {
      "name": ["The name field is required."]
    }
  }
  ```

  ```json 404 Component not found theme={null}
  {
    "message": "No query results for model [BrandPageComponent]."
  }
  ```
</ResponseExample>

<Warning>
  **Common causes of errors on PUT:**

  | Symptom | Cause | Fix |
  | - | - | - |
  | `422` with `name is required` | `name` is always required by the validator, even if unchanged | Always include `"name"` in the body |
  | `422` code uniqueness error | The new `code` is already taken by another component in the same brand | Choose a unique code |
  | `401` redirect to login | Missing or invalid `EF-Access-Key` header, or key doesn't belong to this brand | Check header name and key value |
  | `403` module access | Brand user role doesn't have `components` access | Update role permissions in Project Settings |
  | `html`/`css`/`config` not updating | These fields are not writable via PUT | Use `POST /{component}/editor` to update HTML; use DELETE + POST to replace a component entirely |
</Warning>

***

## Update Component Content

Update the HTML content of a component. Use this endpoint to publish new HTML or save a draft for later review. This is separate from [Update Component](#update-component), which only handles metadata.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Numeric ID **or** `code` string
</ParamField>

<ParamField type="string">
  The HTML content to save
</ParamField>

<ParamField type="boolean">
  When `true`, the HTML is saved as a draft revision and the live component is **not** updated. Draft revisions are returned by [Get Component Content](#get-component-content) until discarded or published. When omitted (or `false`), the HTML is published immediately and any existing draft revisions are discarded.
</ParamField>

<ParamField type="number">
  When saving a draft, pass an existing `revision_id` to update that specific draft instead of creating a new one.
</ParamField>

<ParamField type="number">
  When publishing (not a draft), pass the `revision_id` you last read. If the server has a newer draft, the request returns **409** with `code: "revision_conflict"`.
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/components/{component}/editor
```

```bash cURL (publish) theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/components/custom-hero-section/editor \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<section class=\"hero\"><h1>Updated headline</h1></section>"
  }'
```

```bash cURL (save as draft) theme={null}
curl -X POST "https://app.elasticfunnels.io/api/brands/{brand_id}/components/custom-hero-section/editor?draft=true" \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<section class=\"hero\"><h1>Draft headline</h1></section>"
  }'
```

```javascript JavaScript (publish) theme={null}
await fetch(
  'https://app.elasticfunnels.io/api/brands/{brand_id}/components/custom-hero-section/editor',
  {
    method: 'POST',
    headers: {
      'EF-Access-Key': 'your_api_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ html: '<section class="hero"><h1>Updated</h1></section>' }),
  }
);
```

<ResponseExample>
  ```json 200 Published theme={null}
  {
    "success": true,
    "revision_id": null
  }
  ```

  ```json 200 Saved as draft theme={null}
  {
    "success": true,
    "revision_id": 88
  }
  ```

  ```json 409 Revision conflict (publish) theme={null}
  {
    "success": false,
    "message": "Revision conflict: component changed before publish.",
    "code": "revision_conflict",
    "latest_revision_id": 89
  }
  ```
</ResponseExample>

***

## Get Component Content

Read the current content of a component. If a draft revision exists, the draft HTML is returned along with its `revision_id`. Pass `?published=true` to always get the live published content, ignoring any draft.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Numeric ID **or** `code` string
</ParamField>

<ParamField type="boolean">
  When `true`, returns the published (live) HTML even if a draft revision exists.
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/components/{component}/editor
```

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/components/custom-hero-section/editor" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response (no draft) theme={null}
  {
    "id": 12,
    "name": "Hero Section",
    "code": "custom-hero-section",
    "html": "<section class=\"hero\"><h1>Published headline</h1></section>"
  }
  ```

  ```json Response (draft exists) theme={null}
  {
    "id": 12,
    "name": "Hero Section",
    "code": "custom-hero-section",
    "html": "<section class=\"hero\"><h1>Draft headline</h1></section>",
    "revision_id": 88
  }
  ```
</ResponseExample>

***

## Discard Draft

Discard all draft revisions for a component, reverting to the live published content.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Numeric ID **or** `code` string
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/components/{component}/editor/discard
```

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/components/custom-hero-section/editor/discard \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true
  }
  ```
</ResponseExample>

***

## Get Component Builder Config

Read the full builder config for a component, ready to load into the builder. The server injects brand assets into `config.assets`, normalizes style selectors, and removes empty ID components before returning.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Numeric ID **or** `code` string
</ParamField>

<ParamField type="number">
  Load a specific revision's config instead of the current published state.
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/components/{component}/builder
```

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/components/12/builder" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "pageComponents": [
      {
        "frames": [
          {
            "component": {
              "type": "wrapper",
              "stylable": ["background", "background-color", "background-image"],
              "components": [
                {
                  "type": "text",
                  "attributes": { "id": "c12-hero-heading" },
                  "components": [{ "type": "textnode", "content": "Hello World" }]
                }
              ]
            }
          }
        ],
        "type": "main"
      }
    ],
    "styles": [
      {
        "selectors": ["#c12-hero-heading"],
        "style": { "color": "#333333", "font-size": "32px", "font-weight": "700" }
      },
      {
        "selectors": ["#c12-hero-heading"],
        "mediaText": "768px",
        "atRuleType": "media",
        "style": { "font-size": "22px" }
      }
    ],
    "assets": [
      { "src": "https://cdn.elasticfunnels.io/42/assets/media/logo.png", "type": "image" }
    ],
    "interactions": [],
    "fonts": []
  }
  ```
</ResponseExample>

***

## Save Component Builder Config

Save a full builder config — component tree, styles, rendered HTML, CSS, and interactions — for a component. The server processes the payload before storing it and returns the processed result. **You must replace your local state with the returned config and HTML** before any subsequent save (see [Server-side processing](#server-side-processing) below).

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Numeric ID **or** `code` string
</ParamField>

<ParamField type="string">
  The full builder config as a **JSON string** (not a nested object — stringify it before sending).
</ParamField>

<ParamField type="string">
  Rendered HTML output from the builder
</ParamField>

<ParamField type="string">
  Rendered CSS output from the builder
</ParamField>

<ParamField type="array">
  Interaction definitions attached to this component
</ParamField>

<ParamField type="string">
  Omit (or any value other than `revision`) to publish immediately. Pass `revision` to save as a draft without touching the live component.
</ParamField>

<ParamField type="number">
  When saving a draft (`type=revision`), pass an existing `revision_id` to update that draft instead of creating a new one. Revisions older than 1 hour are always replaced with a new draft regardless.
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/components/{component}/builder
```

```bash cURL (publish) theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/components/12/builder \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "config": "{\"pageComponents\":[{\"frames\":[{\"component\":{\"type\":\"wrapper\",\"components\":[{\"type\":\"text\",\"attributes\":{\"id\":\"hero-heading\"},\"components\":[{\"type\":\"textnode\",\"content\":\"Hello World\"}]}]}}],\"type\":\"main\"}],\"styles\":[{\"selectors\":[\"#hero-heading\"],\"style\":{\"color\":\"#333\",\"font-size\":\"32px\"}}],\"interactions\":[],\"fonts\":[]}",
    "html": "<div id=\"hero-heading\">Hello World</div>",
    "css": "#hero-heading { color: #333; font-size: 32px; }"
  }'
```

```bash cURL (save as draft) theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/components/12/builder \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "revision",
    "config": "...",
    "html": "...",
    "css": "..."
  }'
```

```javascript JavaScript theme={null}
const config = { /* your builder config object */ };
const res = await fetch(
  'https://app.elasticfunnels.io/api/brands/{brand_id}/components/12/builder',
  {
    method: 'POST',
    headers: {
      'EF-Access-Key': 'your_api_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      config: JSON.stringify(config), // must be a string
      html: renderedHtml,
      css: renderedCss,
      interactions: [],
    }),
  }
);

// IMPORTANT: replace your local state with the server-processed result
const { config: processedConfig } = await res.json();
localConfig = processedConfig;
```

<ResponseExample>
  ```json 200 Published theme={null}
  {
    "id": 12,
    "name": "Hero Section",
    "code": "custom-hero-section",
    "config": {
      "pageComponents": [
        {
          "frames": [
            {
              "component": {
                "type": "wrapper",
                "components": [
                  {
                    "type": "text",
                    "attributes": { "id": "c12-hero-heading" },
                    "components": [{ "type": "textnode", "content": "Hello World" }]
                  }
                ]
              }
            }
          ],
          "type": "main"
        }
      ],
      "styles": [
        {
          "selectors": ["#c12-hero-heading"],
          "style": { "color": "#333", "font-size": "32px" }
        }
      ],
      "interactions": [],
      "fonts": []
    }
  }
  ```

  ```json 200 Saved as draft theme={null}
  {
    "id": 12,
    "name": "Hero Section",
    "code": "custom-hero-section",
    "config": { "...": "processed config" },
    "revision_id": 44
  }
  ```

  ```json 422 Malformed config theme={null}
  {
    "message": "Malformed data structure detected. Please refresh the page and try again."
  }
  ```
</ResponseExample>

### Server-side processing

The server modifies the config, HTML, and CSS you send before storing them. The response always contains the **processed** versions. You must store and re-send the returned values — not your original pre-send state — otherwise the next save will be operating on stale data.

What gets modified:

| Field | What happens |
| - | - |
| `config.styles[*].selectors` | All `#id` selectors are normalized to `#c{componentId}-{baseId}`. Any existing `c\d+-` prefixes are stripped first, then the current component ID prefix is applied. This makes cloned and imported components safe to save without selector collisions. |
| `config` component tree `attributes.id` | Same scoping applied recursively to every component node's `id` attribute. |
| `html` element IDs and anchor hrefs | `id="..."` and `href="#..."` values are rewritten to `c{componentId}-{baseId}` format. |
| `css` ID selectors | Same prefix normalization. Hex color values (`#fff`, `#333333`, etc.) are left untouched. |
| `interactions` target/trigger selectors | `#id` references in interaction targets and trigger elements are rewritten to match. |
| `config.styles` | Empty `state` fields removed; `atRuleType: 'media'` is set automatically when `mediaText` is present. |

**Corruption guard**: If `config.data[0]` has a single key `"0"` (a known serialization artifact), the save is aborted with `422` to prevent data loss. This means the config was malformed before being sent — fetch a fresh copy with `GET /builder` and retry.

**Snapshot on publish**: Before overwriting the live component, the server creates a revision snapshot of the current published state (at most once per hour). These snapshots are accessible via [Get Component Revisions](#get-component-revisions).

***

## Get Component Revisions

List revision history for a component. Revisions are created automatically as hourly snapshots when publishing, and explicitly when saving a draft.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Numeric ID **or** `code` string
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/components/{component}/revisions
```

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/components/12/revisions" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "id": 44,
      "created_at": "2024-12-11T09:00:00.000000Z",
      "updated_at": "2024-12-11T09:00:00.000000Z",
      "updated_by": 7,
      "updated_by_user": {
        "id": 7,
        "name": "Jane Smith",
        "email": "jane@example.com"
      }
    },
    {
      "id": 43,
      "created_at": "2024-12-10T14:00:00.000000Z",
      "updated_at": "2024-12-10T14:00:00.000000Z",
      "updated_by": null,
      "updated_by_user": null
    }
  ]
  ```
</ResponseExample>

***

## Delete Component

Delete a component. If the component is still referenced on one or more pages, the request returns a `409` error to prevent accidental data loss. Pass `?force=1` to delete regardless.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Numeric ID **or** `code` string
</ParamField>

<ParamField type="boolean">
  Pass `1` to delete even if the component is still referenced on pages. Pages that reference the component by code will render an empty slot where the component was.
</ParamField>

```bash Request theme={null}
DELETE /api/brands/{brand}/components/{component}
```

```bash cURL theme={null}
curl -X DELETE https://app.elasticfunnels.io/api/brands/{brand_id}/components/14 \
  -H "EF-Access-Key: your_api_key_here"
```

```bash cURL (force delete) theme={null}
curl -X DELETE "https://app.elasticfunnels.io/api/brands/{brand_id}/components/14?force=1" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json 200 Deleted theme={null}
  {
    "success": true
  }
  ```

  ```json 409 Component in use theme={null}
  {
    "error": "component_in_use",
    "message": "Component is still used in 3 page(s). Pass force=1 to delete anyway.",
    "usage_count": 3
  }
  ```

  ```json 404 Not found theme={null}
  {
    "message": "No query results for model [BrandPageComponent]."
  }
  ```
</ResponseExample>

***

## Get Component Usage

Check how many pages reference a component. Optionally return the list of pages for display in tooling.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Numeric ID **or** `code` string
</ParamField>

<ParamField type="string">
  Pass `pages` to include the list of pages that reference this component (capped at 50).
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/components/{component}/usage
```

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/components/custom-guarantee-badge/usage?include=pages" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "component_id": 14,
    "component_code": "custom-guarantee-badge",
    "usage_count": 3,
    "pages": [
      { "id": 101, "slug": "checkout", "title": "Checkout Page" },
      { "id": 102, "slug": "upsell-1", "title": "Upsell Step 1" },
      { "id": 105, "slug": "landing-v2", "title": "Landing Page v2" }
    ]
  }
  ```
</ResponseExample>

***

## Clone Component

Create a copy of a component within the same brand. The clone gets a new auto-generated code and can optionally receive a new name.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Numeric ID **or** `code` string of the component to clone
</ParamField>

<ParamField type="string">
  Name for the cloned component. If omitted, the trailing number in the original name is auto-incremented (e.g. `Hero 1` → `Hero 2`).
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/components/{component}/clone
```

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/components/14/clone \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Guarantee Badge (Copy)" }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "component_id": 15
  }
  ```
</ResponseExample>

***

## Automated Component Provisioning

Provision a full set of reusable brand components in one run. Because [PUT does not update content](#update-component), the correct pattern for programmatic provisioning is to check whether each component exists first, then create it if it does not — not an upsert.

```python Python theme={null}
import requests

BRAND_ID = 42
BASE = f'https://app.elasticfunnels.io/api/brands/{BRAND_ID}'
CDN  = f'https://cdn.elasticfunnels.io/{BRAND_ID}/assets/media'
H    = {'EF-Access-Key': 'your_api_key_here', 'Content-Type': 'application/json'}


def get_existing_codes() -> set:
    """Fetch all component codes already in the brand."""
    r = requests.get(f'{BASE}/components/all?short=true', headers=H)
    r.raise_for_status()
    return {c['code'] for c in r.json()}


def create_component(code: str, name: str, html: str, css: str = '') -> dict:
    payload = {'name': name, 'code': code, 'html': html, 'css': css}
    r = requests.post(f'{BASE}/components', headers=H, json=payload)
    r.raise_for_status()
    comp = r.json()['pageComponent']
    print(f'  ✓  created {code} (id={comp["id"]})')
    return comp


COMPONENTS = [
    {
        'code': 'custom-refund-icon',
        'name': 'Refund Icon',
        'html': f'<div class="refund"><img src="{CDN}/refund-icon.png" alt="Money Back Guarantee"></div>',
        'css':  '.refund { max-width: 80px; margin: 0 auto; }',
    },
    {
        'code': 'custom-guarantee-badge',
        'name': '60-Day Guarantee Badge',
        'html': f'<div class="guarantee"><img src="{CDN}/guarantee-badge.png" alt="60-Day Money Back"></div>',
        'css':  '.guarantee { max-width: 200px; margin: 20px auto; text-align: center; }',
    },
    {
        'code': 'custom-trust-seal',
        'name': 'Trust Seal',
        'html': f'<div class="trust"><img src="{CDN}/trust-seal.svg" alt="Secure Checkout"></div>',
        'css':  '.trust { display: flex; justify-content: center; }',
    },
    {
        'code': 'custom-cc-icons',
        'name': 'Credit Card Icons',
        'html': f'<div class="cc"><img src="{CDN}/cc-icons.png" alt="Visa Mastercard Amex"></div>',
        'css':  '.cc { max-width: 260px; margin: 0 auto; }',
    },
]

print(f'Provisioning components for brand {BRAND_ID}…')
existing = get_existing_codes()

for comp in COMPONENTS:
    if comp['code'] in existing:
        print(f'  –  skipped {comp["code"]} (already exists)')
    else:
        create_component(**comp)

print('Done.')
```

```javascript Node.js theme={null}
const BRAND_ID = 42;
const BASE = `https://app.elasticfunnels.io/api/brands/${BRAND_ID}`;
const CDN  = `https://cdn.elasticfunnels.io/${BRAND_ID}/assets/media`;
const H    = { 'EF-Access-Key': API_KEY, 'Content-Type': 'application/json' };

async function getExistingCodes() {
  const res = await fetch(`${BASE}/components/all?short=true`, { headers: H });
  if (!res.ok) throw new Error(`Failed to fetch components: ${res.status}`);
  const data = await res.json();
  return new Set(data.map(c => c.code));
}

async function createComponent({ code, name, html, css = '' }) {
  const res = await fetch(`${BASE}/components`, {
    method: 'POST',
    headers: H,
    body: JSON.stringify({ name, code, html, css }),
  });
  if (!res.ok) throw new Error(`${code}: ${res.status} ${await res.text()}`);
  const { pageComponent } = await res.json();
  console.log(`  ✓  created ${code} (id=${pageComponent.id})`);
  return pageComponent;
}

const components = [
  { code: 'custom-guarantee-badge', name: '60-Day Guarantee Badge',
    html: `<div class="guarantee"><img src="${CDN}/guarantee-badge.png" alt="Guarantee"></div>`,
    css:  '.guarantee { max-width: 200px; margin: 20px auto; text-align: center; }' },
  { code: 'custom-trust-seal', name: 'Trust Seal',
    html: `<div class="trust"><img src="${CDN}/trust-seal.svg" alt="Secure"></div>`,
    css:  '.trust { display: flex; justify-content: center; }' },
];

const existing = await getExistingCodes();
for (const c of components) {
  if (existing.has(c.code)) {
    console.log(`  –  skipped ${c.code} (already exists)`);
  } else {
    await createComponent(c);
  }
}
```


# Conversions
Source: https://docs.elasticfunnels.io/api-reference/endpoints/conversions

Retrieve and manage order conversions

## List Conversions

Retrieve all conversions (orders) for a project.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="number">
  Page number for pagination (default: 1)
</ParamField>

<ParamField type="number">
  Number of results per page (default: 15)
</ParamField>

<ParamField type="string">
  Search by order code, customer email, or name
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/conversions
```

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/conversions?page=1&per_page=15" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "code": "ORD-12345",
        "customer_email": "customer@example.com",
        "customer_name": "John Doe",
        "total": 149.97,
        "currency": "USD",
        "status": "completed",
        "created_at": "2024-12-10T10:30:00.000000Z"
      }
    ],
    "meta": {
      "current_page": 1,
      "per_page": 15,
      "total": 150
    }
  }
  ```
</ResponseExample>

### Funnel attribution on conversions

List and detail responses can include a nested **`funnel`** object (`id`, `title`) only when the conversion was stored with a `funnel_id` — that comes from matching an **internal EF click** (click code / session), not from the merchant postback alone.

| Field / signal | Meaning |
| - | - |
| `aff_source: "buygoods"` | Sale was recorded via a **Buygoods postback** — it does **not** mean a funnel was matched |
| Empty / missing `funnel` | No internal click ID was matched — common when the buyer reached checkout **directly** (e.g. Buygoods checkout URL) instead of through an **EF-tracked buy link** with a click/subid EF recognizes |
| `funnel` populated | Postback (or checkout) resolved to an EF click that had `funnel_id` on the session |

There is no API setting to backfill funnel on postbacks without click attribution. To get funnel on affiliate sales, traffic must pass through EF-tracked links so Buygoods (or other networks) send back a subid/click EF can resolve.

***

## Get Conversion Details

Retrieve details about a specific conversion.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The order code
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/conversions/{code}
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/conversions/ORD-12345 \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "code": "ORD-12345",
    "customer_email": "customer@example.com",
    "customer_name": "John Doe",
    "customer_phone": "+1234567890",
    "total": 149.97,
    "currency": "USD",
    "status": "completed",
    "items": [
      {
        "product_name": "Main Product",
        "price": 49.99,
        "quantity": 1,
        "type": "main"
      },
      {
        "product_name": "Upsell Product",
        "price": 99.98,
        "quantity": 2,
        "type": "upsell"
      }
    ],
    "shipping_address": {
      "address_1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "country": "US"
    },
    "created_at": "2024-12-10T10:30:00.000000Z"
  }
  ```
</ResponseExample>

***

## Export Conversions

Export conversions to CSV.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Start date (YYYY-MM-DD)
</ParamField>

<ParamField type="string">
  End date (YYYY-MM-DD)
</ParamField>

<ParamField type="string">
  Filter by status: `completed`, `refunded`, `chargeback`
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/conversions/export
```

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/conversions/export \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2024-12-01",
    "end_date": "2024-12-10"
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "message": "Export is being processed",
    "export_id": "exp_abc123",
    "download_url": "https://app.elasticfunnels.io/api/brands/{brand_id}/exports/exp_abc123/download/{token}"
  }
  ```
</ResponseExample>

***

## Refund Conversion

Process a refund for a conversion (requires admin/owner permissions).

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The order code
</ParamField>

<ParamField type="number">
  Refund amount (optional, defaults to full refund)
</ParamField>

<ParamField type="string">
  Refund reason
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/conversions/{code}/refund
```

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/conversions/ORD-12345/refund \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer request"
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "message": "Refund processed successfully",
    "code": "ORD-12345",
    "refund_amount": 149.97,
    "status": "refunded"
  }
  ```
</ResponseExample>


# Courses
Source: https://docs.elasticfunnels.io/api-reference/endpoints/courses

Manage online courses, modules, content, and student enrollments

<Note>
  Course endpoints sit under `/api/brands/{brand}/courses/` with `brandAccess` middleware. Authenticate with `EF-Access-Key`.
</Note>

***

## List Courses

```
GET /api/brands/{brand}/courses
```

<ParamField type="number">
  Results per page (1–100, default: 25)
</ParamField>

<ParamField type="string">
  Search by title, description, slug, or instructor name
</ParamField>

<ParamField type="string">
  `newest`, `oldest`, `created_at`, `updated_at`
</ParamField>

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/courses \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "current_page": 1,
    "data": [
      {
        "id": 1,
        "title": "Gut Health Masterclass",
        "slug": "gut-health",
        "status": "published",
        "delivery_type": "module",
        "language_code": "en",
        "instructor_name": "Dr. Jane Smith",
        "domain_id": 7,
        "modules_count": 6,
        "enrollments_count": 124
      }
    ],
    "per_page": 25,
    "total": 3,
    "last_page": 1
  }
  ```
</ResponseExample>

***

## List Courses (Unpaginated)

```
GET /api/brands/{brand}/courses/all
```

Returns `{ id, title }` for all courses — useful for dropdowns.

***

## Get Course

```
GET /api/brands/{brand}/courses/{course}
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 1,
    "title": "Gut Health Masterclass",
    "slug": "gut-health",
    "status": "published",
    "delivery_type": "module",
    "language_code": "en",
    "description": "Learn how to improve your gut health...",
    "instructor_name": "Dr. Jane Smith",
    "instructor_photo": "https://cdn.elasticfunnels.io/42/assets/media/instructor.jpg",
    "logo": null,
    "cover": "https://cdn.elasticfunnels.io/42/assets/media/cover.jpg",
    "domain_id": 7,
    "domain": { "id": 7, "domain": "courses.mybrand.com" },
    "show_module_titles": true,
    "allow_comments": false,
    "details_page_id": null,
    "module_page_id": 101,
    "content_page_id": 102,
    "enrollment_email_template_id": null,
    "enrollments_count": 124
  }
  ```
</ResponseExample>

***

## Create Course

```
POST /api/brands/{brand}/courses
```

<ParamField type="string">
  Course title (max 255)
</ParamField>

<ParamField type="string">
  Language code (e.g. `en`, `pt`)
</ParamField>

<ParamField type="string">
  Course description
</ParamField>

<ParamField type="string">
  `draft` or `published`
</ParamField>

<ParamField type="string">
  `embedded` (content lives inline on a page) or `module` (dedicated course pages on a domain)
</ParamField>

<ParamField type="number">
  Required when `delivery_type` is `module`. Must be an existing brand domain.
</ParamField>

<ParamField type="string">
  Required when `delivery_type` is `module`. Must be unique per `brand_id` + `domain_id`.
</ParamField>

<ParamField type="string">
  Instructor display name (max 255)
</ParamField>

<ParamField type="file | string">
  Instructor photo — upload as file (multipart) or provide as URL string
</ParamField>

<ParamField type="file | string">
  Course logo — upload as file or URL string
</ParamField>

<ParamField type="file | string">
  Cover image — upload as file or URL string
</ParamField>

<ParamField type="boolean">
  Show module titles in the course outline
</ParamField>

<ParamField type="boolean">
  Enable commenting on content
</ParamField>

<ParamField type="string">
  Course category name (max 255)
</ParamField>

<ParamField type="number">
  Page ID for the course details/landing page
</ParamField>

<ParamField type="number">
  Page ID for module listing
</ParamField>

<ParamField type="number">
  Page ID for content viewing
</ParamField>

<ParamField type="number">
  Email template ID to send upon enrollment
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/courses \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Gut Health Masterclass",
    "language_code": "en",
    "description": "Learn how to improve your gut health naturally.",
    "status": "draft",
    "delivery_type": "module",
    "domain_id": 7,
    "slug": "gut-health",
    "instructor_name": "Dr. Jane Smith"
  }'
```

<ResponseExample>
  ```json 200 Created theme={null}
  {
    "course": {
      "id": 1,
      "title": "Gut Health Masterclass",
      "slug": "gut-health",
      "status": "draft",
      "brand_id": 42,
      "created_at": "2024-12-11T10:00:00.000000Z"
    }
  }
  ```

  ```json 403 Plan limit theme={null}
  {
    "error": "Upgrade required to create courses",
    "plan_error": {
      "message": "Your current plan does not allow creating courses.",
      "upgrade_info": {}
    }
  }
  ```
</ResponseExample>

***

## Update Course

```
PUT /api/brands/{brand}/courses/{course}
```

Same body as Create. `title`, `language_code`, `description`, `status`, and `delivery_type` are required.

***

## Delete Course

```
DELETE /api/brands/{brand}/courses/{course}
```

<ResponseExample>
  ```json Response theme={null}
  { "success": true }
  ```
</ResponseExample>

***

## Copy Course to Another Brand

```
POST /api/brands/{brand}/courses/copy
```

<ParamField type="number">
  Source course ID
</ParamField>

<ParamField type="number">
  Target brand ID
</ParamField>

<ParamField type="string">
  Title for the copied course in the target brand
</ParamField>

<ResponseExample>
  ```json Response theme={null}
  {
    "course_id": 5
  }
  ```
</ResponseExample>

***

## Enrollments

### List Enrollments

```
GET /api/brands/{brand}/courses/{course}/enrollments
```

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": "es-enroll-abc123",
        "email": "student@example.com",
        "name": "Jane Student",
        "user_id": 99,
        "notes": null,
        "created_at": "2024-12-01T00:00:00Z",
        "completed_content_ids": [10, 11],
        "progress_percent": 33,
        "last_content_id": 11,
        "last_module_id": 2
      }
    ]
  }
  ```
</ResponseExample>

### Get Enrollment

```
GET /api/brands/{brand}/courses/{course}/enrollments/{enrollment}
```

<ParamField type="string">
  Elasticsearch document ID for the enrollment
</ParamField>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": { /* same enrollment object */ }
  }
  ```
</ResponseExample>

### Enroll Student

```
POST /api/brands/{brand}/courses/{course}/enrollments
```

<ParamField type="string">
  Student email address. Returns 422 if already enrolled.
</ParamField>

<ParamField type="string">
  Student display name (max 255)
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/courses/1/enrollments \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "student@example.com", "name": "Jane Student"}'
```

<ResponseExample>
  ```json 201 Enrolled theme={null}
  {
    "data": {
      "id": "es-enroll-abc123",
      "email": "student@example.com",
      "name": "Jane Student",
      "created_at": "2024-12-11T10:00:00Z"
    }
  }
  ```

  ```json 422 Already enrolled theme={null}
  {
    "message": "Failed to create enrollment",
    "errors": {
      "email": ["This student is already enrolled in this course."]
    }
  }
  ```
</ResponseExample>

### Update Enrollment Notes

```
PUT /api/brands/{brand}/courses/{course}/enrollments/{enrollment}
```

<ParamField type="string">
  Internal notes about the enrollment (max 10,000 chars)
</ParamField>

### Complete Content Item

Mark a specific content item as completed for an enrolled student.

```
POST /api/brands/{brand}/courses/{course}/enrollments/{enrollment}/complete
```

<ParamField type="number">
  The course content item ID to mark as complete
</ParamField>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "completed_content_ids": [10, 11, 12],
      "progress_percent": 50,
      "last_content_id": 12
    }
  }
  ```
</ResponseExample>

<Info>
  This endpoint is **idempotent** — marking an already-completed item again does not create duplicates.
</Info>

### Remove Enrollment

```
DELETE /api/brands/{brand}/courses/{course}/enrollments/{enrollment}
```

<ResponseExample>
  ```json Response theme={null}
  { "success": true }
  ```
</ResponseExample>

***

## Modules

### List Modules

```
GET /api/brands/{brand}/courses/{course}/modules
```

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": 3,
        "title": "Module 1: Introduction",
        "description": "Overview of gut health fundamentals.",
        "order": 1,
        "contents": [
          { "id": 10, "title": "What is Gut Flora?", "type": "video", "order": 1 },
          { "id": 11, "title": "The Gut-Brain Axis", "type": "text", "order": 2 }
        ]
      }
    ]
  }
  ```
</ResponseExample>

### List Modules (Unpaginated)

```
GET /api/brands/{brand}/courses/{course}/modules/all
```

Returns `{ id, title }` array — cached.

### Create Module

```
POST /api/brands/{brand}/courses/{course}/modules
```

<ParamField type="string">
  Module title (max 255)
</ParamField>

<ParamField type="string">
  Module description
</ParamField>

### Update Module

```
PUT /api/brands/{brand}/courses/{course}/modules/{module}
```

### Delete Module

```
DELETE /api/brands/{brand}/courses/{course}/modules/{module}
```

### Reorder Modules

```
POST /api/brands/{brand}/courses/{course}/modules/order
```

<ParamField type="object">
  Map of `{ "<module_id>": <integer order>, ... }`
</ParamField>

***

## Notes

<Info>
  * Enrollment IDs are Elasticsearch document IDs (strings), not numeric database IDs
  * File uploads (`logo`, `cover`, `instructor_photo`) are stored on BunnyCDN — you can provide a URL string instead of uploading a file
  * The `copy` endpoint replicates the course's modules and all content to the target brand
  * `progress_percent` is recalculated automatically when content is marked complete
</Info>


# CRM
Source: https://docs.elasticfunnels.io/api-reference/endpoints/crm

Manage CRM entities, pipelines, stages, custom fields, and entries

<Note>
  All CRM endpoints are under the prefix `/api/brands/{brand}/crm/` and authenticate via `EF-Access-Key`.
</Note>

The CRM is structured as:

```
Entity  (e.g. "Leads", "Deals")
  └── Pipeline  (e.g. "Sales Pipeline")
        └── Stage  (e.g. "Prospect", "Qualified", "Closed")
  └── Fields  (custom fields defined per entity)
  └── Entries  (the actual records)
```

***

## Entity Presets

Before creating a custom entity you can list and apply built-in presets (e.g. Leads, Contacts, Deals) which come pre-configured with pipelines and fields.

```
GET /api/brands/{brand}/crm/entity-presets
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/crm/entity-presets \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "presets": [
      { "key": "leads",    "label": "Leads",    "description": "Track inbound leads through a sales process" },
      { "key": "contacts", "label": "Contacts", "description": "Manage contacts and customers" },
      { "key": "deals",    "label": "Deals",    "description": "Deal tracking with revenue stages" }
    ]
  }
  ```
</ResponseExample>

***

## Entities

Entities define the type of record tracked in the CRM (e.g. "Leads", "Customers"). Each brand can have multiple entities.

### List Entities

```
GET /api/brands/{brand}/crm/entities
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/crm/entities \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "id": 1,
      "name": "Leads",
      "slug": "leads",
      "singular_name": "Lead",
      "plural_name": "Leads",
      "icon": "user",
      "color": "#3b82f6",
      "brand_id": 42,
      "pipelines_count": 1,
      "fields_count": 5
    }
  ]
  ```
</ResponseExample>

### Get Entity

```
GET /api/brands/{brand}/crm/entities/{entity}
```

Returns the entity with its full `pipelines` (including `stages`) and `fields` loaded.

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 1,
    "name": "Leads",
    "slug": "leads",
    "pipelines": [
      {
        "id": 1,
        "name": "Sales Pipeline",
        "stages": [
          { "id": 1, "name": "New Lead",   "position": 0, "color": "#94a3b8" },
          { "id": 2, "name": "Contacted",  "position": 1, "color": "#3b82f6" },
          { "id": 3, "name": "Qualified",  "position": 2, "color": "#10b981" },
          { "id": 4, "name": "Closed Won", "position": 3, "color": "#22c55e" }
        ]
      }
    ],
    "fields": [
      { "id": 1, "name": "Email",   "key": "email",   "type": "text" },
      { "id": 2, "name": "Phone",   "key": "phone",   "type": "text" },
      { "id": 3, "name": "Source",  "key": "source",  "type": "select",
        "options": ["Facebook", "Google", "Organic"] }
    ]
  }
  ```
</ResponseExample>

### Create Entity

```
POST /api/brands/{brand}/crm/entities
```

<ParamField type="string">
  Display name (e.g. `Leads`)
</ParamField>

<ParamField type="string">
  URL-safe identifier — lowercase alphanumeric, hyphens, underscores (e.g. `leads`). Must be unique per brand.
</ParamField>

<ParamField type="string">
  Singular label (e.g. `Lead`)
</ParamField>

<ParamField type="string">
  Plural label (e.g. `Leads`)
</ParamField>

<ParamField type="string">
  Icon identifier (max 64 chars)
</ParamField>

<ParamField type="string">
  Hex color (max 64 chars)
</ParamField>

<ParamField type="string">
  Optional preset key from [Entity Presets](#entity-presets). When set, pre-populates pipelines and fields.
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/crm/entities \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Leads",
    "slug": "leads",
    "singular_name": "Lead",
    "plural_name": "Leads",
    "icon": "user",
    "color": "#3b82f6",
    "preset": "leads"
  }'
```

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": 1,
    "name": "Leads",
    "slug": "leads",
    "singular_name": "Lead",
    "plural_name": "Leads",
    "icon": "user",
    "color": "#3b82f6",
    "brand_id": 42,
    "created_at": "2024-12-11T10:00:00.000000Z"
  }
  ```

  ```json 422 Duplicate slug theme={null}
  {
    "errors": {
      "slug": ["The slug has already been taken."]
    }
  }
  ```
</ResponseExample>

### Update Entity

```
PUT /api/brands/{brand}/crm/entities/{entity}
```

Same fields as Create, all optional on update.

### Delete Entity

```
DELETE /api/brands/{brand}/crm/entities/{entity}
```

***

## Pipelines

Pipelines belong to an entity and contain an ordered list of stages.

### List Pipelines

```
GET /api/brands/{brand}/crm/entities/{entity}/pipelines
```

### Get Pipeline

```
GET /api/brands/{brand}/crm/pipelines/{pipeline}
```

### Create Pipeline

```
POST /api/brands/{brand}/crm/entities/{entity}/pipelines
```

<ParamField type="string">
  Pipeline name (e.g. `Sales Pipeline`)
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/crm/entities/1/pipelines \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sales Pipeline"}'
```

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": 1,
    "name": "Sales Pipeline",
    "crm_entity_id": 1,
    "brand_id": 42,
    "created_at": "2024-12-11T10:00:00.000000Z"
  }
  ```
</ResponseExample>

### Update Pipeline

```
PUT /api/brands/{brand}/crm/pipelines/{pipeline}
```

### Delete Pipeline

```
DELETE /api/brands/{brand}/crm/pipelines/{pipeline}
```

***

## Stages

Stages belong to a pipeline and represent progress steps (e.g. "Prospect → Qualified → Closed").

### List Stages

```
GET /api/brands/{brand}/crm/pipelines/{pipeline}/stages
```

### Get Stage

```
GET /api/brands/{brand}/crm/stages/{stage}
```

### Create Stage

```
POST /api/brands/{brand}/crm/pipelines/{pipeline}/stages
```

<ParamField type="string">
  Stage name (e.g. `Qualified`)
</ParamField>

<ParamField type="string">
  Hex color for the stage badge
</ParamField>

<ParamField type="number">
  Sort order (0-based integer). Use [Reorder](#reorder-stages) to batch-update positions.
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/crm/pipelines/1/stages \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Qualified", "color": "#10b981", "position": 2}'
```

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": 3,
    "name": "Qualified",
    "color": "#10b981",
    "position": 2,
    "pipeline_id": 1,
    "created_at": "2024-12-11T10:00:00.000000Z"
  }
  ```
</ResponseExample>

### Update Stage

```
PUT /api/brands/{brand}/crm/stages/{stage}
```

### Reorder Stages

```
PUT /api/brands/{brand}/crm/stages/reorder
```

<ParamField type="array">
  Array of `{id, position}` objects in the desired order.
</ParamField>

```bash cURL theme={null}
curl -X PUT https://app.elasticfunnels.io/api/brands/{brand_id}/crm/stages/reorder \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "stages": [
      {"id": 1, "position": 0},
      {"id": 3, "position": 1},
      {"id": 2, "position": 2},
      {"id": 4, "position": 3}
    ]
  }'
```

### Delete Stage

```
DELETE /api/brands/{brand}/crm/stages/{stage}
```

***

## Custom Fields

Custom fields define the schema for entry data. Each entity has its own set of fields.

### List Fields

```
GET /api/brands/{brand}/crm/entities/{entity}/fields
```

### Get Field

```
GET /api/brands/{brand}/crm/fields/{field}
```

### Create Field

```
POST /api/brands/{brand}/crm/entities/{entity}/fields
```

<ParamField type="string">
  Field label (e.g. `Email Address`)
</ParamField>

<ParamField type="string">
  Slug key used in `values` on entries (e.g. `email`). Lowercase alphanumeric + underscores.
</ParamField>

<ParamField type="string">
  Field type: `text`, `number`, `date`, `boolean`, `select`, `multi_select`, `url`, `email`, `phone`
</ParamField>

<ParamField type="array">
  For `select` and `multi_select` types — array of option strings.
</ParamField>

<ParamField type="boolean">
  Whether this field is required on entry creation (default: `false`)
</ParamField>

<ParamField type="number">
  Display order
</ParamField>

<ParamField type="object">
  Optional reporting metadata. Supported keys: `reportable` (boolean), `aggregation_type` (`numeric`, `categorical`, `date`, `boolean`), `baseline` (`min`/`max` numbers), `bucket_size` (positive number), and `preferred_chart` (`kpi`, `histogram`, `pie`, `bar`, `line`).
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/crm/entities/1/fields \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lead Source",
    "key": "lead_source",
    "type": "select",
    "options": ["Facebook", "Google", "Organic", "Referral"],
    "reporting_config": {
      "reportable": true,
      "aggregation_type": "categorical",
      "preferred_chart": "bar"
    },
    "required": false,
    "position": 2
  }'
```

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": 4,
    "name": "Lead Source",
    "key": "lead_source",
    "type": "select",
    "options": ["Facebook", "Google", "Organic", "Referral"],
    "reporting_config": {
      "reportable": true,
      "aggregation_type": "categorical",
      "preferred_chart": "bar"
    },
    "required": false,
    "position": 2,
    "crm_entity_id": 1,
    "created_at": "2024-12-11T10:00:00.000000Z"
  }
  ```
</ResponseExample>

### Update Field

```
PUT /api/brands/{brand}/crm/fields/{field}
```

Accepts the same editable field properties as Create Field, including `reporting_config`.

### Delete Field

```
DELETE /api/brands/{brand}/crm/fields/{field}
```

***

## Entries

Entries are the individual records in a CRM entity (e.g. a single lead or deal). They are stored and queried via Elasticsearch.

### List Entries

```
GET /api/brands/{brand}/crm/entities/{entity}/entries
```

<ParamField type="string">
  Entity ID
</ParamField>

<ParamField type="number">
  Results per page (max 100, default: 25)
</ParamField>

<ParamField type="number">
  Page number (default: 1)
</ParamField>

<ParamField type="number">
  Filter by pipeline
</ParamField>

<ParamField type="number">
  Filter by stage
</ParamField>

<ParamField type="string">
  Filter by external reference type (e.g. `conversion`, `lead`)
</ParamField>

<ParamField type="string">
  Filter by external reference ID
</ParamField>

<ParamField type="string">
  Full-text search on `title`
</ParamField>

<ParamField type="boolean">
  Attach matched customer record to each entry (default: `false`)
</ParamField>

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/crm/entities/1/entries?pipeline_id=1&stage_id=2&per_page=50" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": "es-doc-id-abc",
        "title": "Jane Doe",
        "pipeline_id": 1,
        "stage_id": 2,
        "crm_entity_id": 1,
        "brand_id": 42,
        "reference_type": "conversion",
        "reference_id": "conv-123",
        "assigned_to_user_id": null,
        "values": [
          { "key": "email",       "value": "jane@example.com" },
          { "key": "lead_source", "value": "Facebook" }
        ],
        "values_flat": {
          "email": "jane@example.com",
          "lead_source": "Facebook"
        },
        "updated_at": "2024-12-10T14:00:00Z"
      }
    ],
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 87
  }
  ```
</ResponseExample>

### Get Entry

```
GET /api/brands/{brand}/crm/entries/{entry}
GET /api/brands/{brand}/crm/entities/{entity}/entries/{entry}
```

### Create Entry

```
POST /api/brands/{brand}/crm/entities/{entity}/entries
```

<ParamField type="string">
  Human-readable label for the entry (e.g. the lead's name or email)
</ParamField>

<ParamField type="number">
  ID of the pipeline this entry belongs to
</ParamField>

<ParamField type="number">
  ID of the initial stage
</ParamField>

<ParamField type="object">
  Flat key-value object of custom field values (e.g. `{"email": "jane@example.com", "lead_source": "Facebook"}`). Keys must match a defined field `key` on the entity.
</ParamField>

<ParamField type="string">
  External ID to link the entry to another record (e.g. a conversion ID)
</ParamField>

<ParamField type="string">
  Type of external reference (e.g. `conversion`, `lead`, `order`)
</ParamField>

<ParamField type="number">
  Assign to a specific team member by user ID
</ParamField>

<ParamField type="number">
  Assign to a CRM team by team ID
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/crm/entities/1/entries \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Jane Doe",
    "pipeline_id": 1,
    "stage_id": 1,
    "reference_type": "conversion",
    "reference_id": "conv-123",
    "values": {
      "email": "jane@example.com",
      "phone": "+15551234567",
      "lead_source": "Facebook"
    }
  }'
```

```python Python theme={null}
import requests

r = requests.post(
    'https://app.elasticfunnels.io/api/brands/{brand_id}/crm/entities/1/entries',
    headers={'EF-Access-Key': 'your_api_key_here', 'Content-Type': 'application/json'},
    json={
        'title': 'Jane Doe',
        'pipeline_id': 1,
        'stage_id': 1,
        'reference_type': 'conversion',
        'reference_id': 'conv-123',
        'values': {
            'email': 'jane@example.com',
            'lead_source': 'Facebook',
        },
    },
)
entry = r.json()
print(entry['id'])
```

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": "es-doc-id-xyz",
    "title": "Jane Doe",
    "pipeline_id": 1,
    "stage_id": 1,
    "crm_entity_id": 1,
    "brand_id": 42,
    "reference_type": "conversion",
    "reference_id": "conv-123",
    "values": [
      { "key": "email",       "value": "jane@example.com" },
      { "key": "lead_source", "value": "Facebook" }
    ],
    "values_flat": {
      "email": "jane@example.com",
      "lead_source": "Facebook"
    },
    "created_at": "2024-12-11T10:00:00Z",
    "updated_at": "2024-12-11T10:00:00Z"
  }
  ```

  ```json 422 Missing required fields theme={null}
  {
    "errors": {
      "title":       ["The title field is required."],
      "pipeline_id": ["The pipeline id field is required."],
      "stage_id":    ["The stage id field is required."]
    }
  }
  ```
</ResponseExample>

### Update Entry

```
PUT /api/brands/{brand}/crm/entries/{entry}
PUT /api/brands/{brand}/crm/entities/{entity}/entries/{entry}
```

Same body as Create. All fields optional — only provided fields are updated.

```bash cURL — update values and reassign theme={null}
curl -X PUT https://app.elasticfunnels.io/api/brands/{brand_id}/crm/entries/es-doc-id-xyz \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "values": { "lead_source": "Google", "phone": "+15559876543" },
    "assigned_to_user_id": 7
  }'
```

### Move Entry to Stage

Move an entry to a different stage within the same pipeline.

```
PUT /api/brands/{brand}/crm/entries/{entry}/stage
PUT /api/brands/{brand}/crm/entities/{entity}/entries/{entry}/stage
```

<ParamField type="number">
  Target stage ID (must belong to the entry's current pipeline)
</ParamField>

```bash cURL theme={null}
curl -X PUT https://app.elasticfunnels.io/api/brands/{brand_id}/crm/entries/es-doc-id-xyz/stage \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"stage_id": 3}'
```

<ResponseExample>
  ```json 200 Stage updated theme={null}
  {
    "id": "es-doc-id-xyz",
    "stage_id": 3,
    "updated_at": "2024-12-11T10:05:00Z"
  }
  ```
</ResponseExample>

### Delete Entry

```
DELETE /api/brands/{brand}/crm/entries/{entry}
DELETE /api/brands/{brand}/crm/entities/{entity}/entries/{entry}
```

***

## Automation: Create CRM Entry from Conversion

A common pattern is creating a CRM entry whenever a conversion is recorded. Using the EF automation pipeline or an external webhook:

```python Python theme={null}
import requests

BRAND_ID = 42
API_KEY = "your_api_key_here"
BASE = f"https://app.elasticfunnels.io/api/brands/{BRAND_ID}/crm"
H = {"EF-Access-Key": API_KEY, "Content-Type": "application/json"}

def create_lead_from_conversion(conversion: dict) -> dict:
    """Create a CRM entry from a conversion webhook payload."""
    return requests.post(
        f"{BASE}/entities/1/entries",
        headers=H,
        json={
            "title": f"{conversion['first_name']} {conversion['last_name']}",
            "pipeline_id": 1,
            "stage_id": 1,   # "New Lead"
            "reference_type": "conversion",
            "reference_id": str(conversion["id"]),
            "values": {
                "email":       conversion.get("email"),
                "phone":       conversion.get("phone"),
                "lead_source": conversion.get("utm_source", "unknown"),
            },
        },
    ).json()
```


# Customers
Source: https://docs.elasticfunnels.io/api-reference/endpoints/customers

List, search, and export customer records

<Note>
  Customer endpoints sit under `/api/brands/{brand}/customers/` with `moduleAccess:customers` middleware. Authenticate with `EF-Access-Key`.
</Note>

Customer records are built from conversion and tracking events (purchases, abandoned carts, chargebacks). They are stored in Elasticsearch and cannot be created via API directly — they are created automatically when conversions are recorded.

***

## List Customers

```
GET /api/brands/{brand}/customers
```

<ParamField type="number">
  Results per page (1–100, default: 25)
</ParamField>

<ParamField type="string">
  Filter by customer type: `customer` (purchases only) or `abandon` (abandoned carts only)
</ParamField>

<ParamField type="string">
  Search by email, name, or phone
</ParamField>

<ParamField type="string">
  Sort field. Any of the sortable columns below.
</ParamField>

<ParamField type="string">
  `asc` or `desc`
</ParamField>

<ParamField type="array">
  Subset of columns to return. Allowed values: `customer_email`, `customer_name`, `customer_first_name`, `customer_last_name`, `customer_phone`, `customer_country`, `customer_state`, `customer_city`, `last_order_date`, `first_order_date`, `total_orders`, `total_revenue`, `total_refunds`, `total_chargebacks`, `lifetime_value`, `order_frequency`, `products_purchased`, `is_abandoned_customer`, `abandoned_value`
</ParamField>

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/customers?sort=total_revenue&sort_direction=desc&per_page=50" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "current_page": 1,
    "data": [
      {
        "customer_email": "jane@example.com",
        "customer_name": "Jane Doe",
        "customer_first_name": "Jane",
        "customer_last_name": "Doe",
        "customer_phone": "+15551234567",
        "customer_country": "US",
        "customer_state": "CA",
        "customer_city": "Los Angeles",
        "first_order_date": "2024-06-01T00:00:00Z",
        "last_order_date": "2024-12-01T00:00:00Z",
        "total_orders": 3,
        "total_revenue": 207.00,
        "total_refunds": 0,
        "total_chargebacks": 0,
        "lifetime_value": 207.00,
        "order_frequency": 90,
        "is_abandoned_customer": false,
        "abandoned_value": 0
      }
    ],
    "per_page": 25,
    "total": 1842,
    "last_page": 74
  }
  ```
</ResponseExample>

***

## Quick Access Stats

Returns customer counts by type — useful for dashboard badges.

```
GET /api/brands/{brand}/customers/quick-access
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/customers/quick-access \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "all": 1842,
    "customers": 1205,
    "abandons": 637,
    "chargebacks": 14,
    "refunds": 38
  }
  ```
</ResponseExample>

***

## Get Customer Details

Retrieve the full profile for a single customer by email address — includes lifetime stats, order history, subscriptions, and notes.

```
GET /api/brands/{brand}/customers/{customerEmail}/details
```

<ParamField type="string">
  Customer's email address (URL-encoded if it contains special characters)
</ParamField>

<ParamField type="boolean">
  Include full order history (default: true)
</ParamField>

<ParamField type="boolean">
  Include active subscriptions (default: true)
</ParamField>

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/customers/jane%40example.com/details" \
  -H "EF-Access-Key: your_api_key_here"
```

```python Python theme={null}
import requests, urllib.parse

email = urllib.parse.quote("jane@example.com", safe="")
r = requests.get(
    f'https://app.elasticfunnels.io/api/brands/{brand_id}/customers/{email}/details',
    headers={'EF-Access-Key': 'your_api_key_here'},
)
print(r.json())
```

<ResponseExample>
  ```json Response theme={null}
  {
    "customer": {
      "email": "jane@example.com",
      "name": "Jane Doe",
      "phone": "+15551234567",
      "country": "US",
      "state": "CA",
      "city": "Los Angeles",
      "address": "123 Main St"
    },
    "stats": {
      "total_orders": 3,
      "total_revenue": 207.00,
      "total_refunds": 0,
      "total_chargebacks": 0,
      "lifetime_value": 207.00,
      "first_order_date": "2024-06-01T00:00:00Z",
      "last_order_date": "2024-12-01T00:00:00Z",
      "average_order_value": 69.00
    },
    "orders": [
      {
        "id": "conv-abc",
        "date": "2024-12-01T00:00:00Z",
        "total": 69.00,
        "products": ["1 Bottle"],
        "status": "approved"
      }
    ],
    "subscriptions": [
      {
        "id": 12,
        "status": "active",
        "product": "Monthly Bundle",
        "next_charge_date": "2025-01-01"
      }
    ]
  }
  ```

  ```json 404 Not found theme={null}
  {
    "message": "Customer not found."
  }
  ```
</ResponseExample>

***

## Export Customers

Queue a CSV export of customer records. An email is sent when the export is ready.

```
POST /api/brands/{brand}/customers/export
```

<ParamField type="array">
  Filter conditions (same keys as the list endpoint `?type`, `?q`, etc.)
</ParamField>

<ParamField type="array">
  Limit export to specific email addresses
</ParamField>

<ParamField type="array">
  Columns to include (subset of the allowed column list above)
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/customers/export \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "columns": ["customer_email", "customer_name", "total_revenue", "last_order_date"],
    "filters": {"type": "customer"}
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "message": "Export started. You will receive an email when it is ready."
  }
  ```
</ResponseExample>

***

## Notes

<Info>
  * Customer records are read-only — they are created automatically from conversion events
  * The `{customerEmail}` path parameter should be URL-encoded
  * Sorting and filtering use Elasticsearch under the hood; large result sets may be slightly delayed
  * The `columns` parameter controls both what is fetched and what is returned, reducing response size for large lists
</Info>


# Domains
Source: https://docs.elasticfunnels.io/api-reference/endpoints/domains

Manage custom domains, SSL certificates, DNS validation, and tracking domains

<Note>
  Domain endpoints sit under `/api/brands/{brand}/` (no `moduleAccess` required). Authenticate with `EF-Access-Key`.
</Note>

***

## List Domains

```
GET /api/brands/{brand}/domains
```

<Note>
  Paginated list responses use Laravel's standard shape: the domain rows are in **`data`**, not `domains`. Example: `response.data[0].domain`.
</Note>

<ParamField type="number">
  Results per page (1–100, default: 25)
</ParamField>

<ParamField type="string">
  Search by domain name
</ParamField>

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/domains \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "current_page": 1,
    "data": [
      {
        "id": 7,
        "domain": "checkout.mybrand.com",
        "dedicated_domain": true,
        "status": "validated",
        "ssl_ready": true,
        "cname_validated": true,
        "is_tracking_domain": false,
        "brand_id": 42,
        "created_at": "2024-06-01T00:00:00.000000Z"
      }
    ],
    "per_page": 25,
    "total": 2,
    "last_page": 1
  }
  ```
</ResponseExample>

***

## List All Domains (Unpaginated)

```
GET /api/brands/{brand}/domains/all
```

Returns all domains as a **bare JSON array** at the root (no `data` or `domains` wrapper) — used for dropdown selectors. Each item includes `id`, `domain`, and `merchant_code`.

***

## Get Domain

```
GET /api/brands/{brand}/domains/{domain}
```

***

## Add Domain

```
POST /api/brands/{brand}/domains
```

<ParamField type="string">
  Fully-qualified domain name (e.g. `checkout.mybrand.com`). Must be globally unique.
</ParamField>

<ParamField type="boolean">
  `true` for custom domains (requires DNS setup); `false` for subdomains on the platform's root domain.
</ParamField>

```bash cURL — add custom domain theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/domains \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"domain": "checkout.mybrand.com", "dedicated_domain": true}'
```

```bash cURL — add platform subdomain theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/domains \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"domain": "mybrand", "dedicated_domain": false}'
```

<ResponseExample>
  ```json 200 Custom domain added theme={null}
  {
    "id": 7,
    "domain": "checkout.mybrand.com",
    "dedicated_domain": true,
    "status": "pending-cname",
    "ssl_ready": false,
    "cname_validated": false
  }
  ```

  ```json 422 Already taken theme={null}
  {
    "errors": {
      "domain": ["The domain has already been taken."]
    }
  }
  ```
</ResponseExample>

***

## Update Domain

```
PUT /api/brands/{brand}/domains/{domain}
```

***

## Delete Domain

```
DELETE /api/brands/{brand}/domains/{domain}
```

<ResponseExample>
  ```json Response theme={null}
  { "success": true }
  ```
</ResponseExample>

***

## Get Validation Instructions

Returns the DNS records that must be set to validate a custom domain. Call this after adding a domain to get the CNAME record to configure.

```
GET /api/brands/{brand}/domains/{domain}/validation-instructions
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/domains/7/validation-instructions \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "domain": "checkout.mybrand.com",
    "is_apex": false,
    "records": [
      {
        "type": "TXT",
        "name": "_cf-custom-hostname.checkout.mybrand.com.",
        "value": "abc123-verification-token",
        "description": "Verifies domain ownership"
      },
      {
        "type": "CNAME",
        "name": "checkout",
        "value": "proxy.elasticfunnels.io",
        "description": "Points your subdomain to our platform"
      }
    ],
    "platform_domain": "proxy.elasticfunnels.io",
    "status": "pending-cname",
    "cloudflare_status": null,
    "ssl_status": null,
    "cloudflare_verification_errors": null
  }
  ```
</ResponseExample>

***

## Validate Domain

Queue an asynchronous DNS / Cloudflare validation job for a domain. This endpoint does **not** return the final validation result synchronously.

**Workflow:** `GET validation-instructions` → configure DNS → `POST validate` → poll `GET /domains/{id}` until `status` and `cname_validated` update.

```
POST /api/brands/{brand}/domains/{domain}/validate
```

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/domains/7/validate \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json 200 Queued (normal response) theme={null}
  {
    "queued": true
  }
  ```
</ResponseExample>

<Note>
  After calling validate, the domain `status` is set to `pending-cloudflare` while background jobs run. Poll [Get Domain](#get-domain) or [List Domains](#list-domains) for `cname_validated` and `status` changes — do not expect `success` / `cname_validated` in the validate response body.
</Note>

***

## Test Domain Configuration

Run a full connectivity and configuration test for a domain.

```
GET /api/brands/{brand}/domains/{domain}/test-configuration
```

<ResponseExample>
  ```json Response theme={null}
  {
    "dns_ok": true,
    "ssl_ok": true,
    "http_reachable": true,
    "https_reachable": true,
    "status": "healthy"
  }
  ```
</ResponseExample>

***

## Request SSL Certificate

Provision or re-provision an SSL certificate for a validated custom domain.

```
POST /api/brands/{brand}/domains/{domain}/request-ssl
GET  /api/brands/{brand}/domains/{domain}/request-ssl
```

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/domains/7/request-ssl \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "message": "SSL certificate provisioning started. This may take a few minutes."
  }
  ```
</ResponseExample>

***

## Move Domain (Preview)

Preview what pages and components would be affected by moving all content from one domain to another.

```
POST /api/brands/{brand}/domains/{domain}/move/preview
```

<ParamField type="number">
  Target domain ID to move content to
</ParamField>

<ResponseExample>
  ```json Response theme={null}
  {
    "pages_affected": 12,
    "components_affected": 3,
    "preview": [
      { "id": 101, "title": "Landing Page", "current_domain": "old.mybrand.com", "new_domain": "new.mybrand.com" }
    ]
  }
  ```
</ResponseExample>

***

## Move Domain (Apply)

Execute the domain migration — update all pages and components from one domain to another.

```
POST /api/brands/{brand}/domains/{domain}/move/apply
```

<ParamField type="number">
  Target domain ID
</ParamField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "pages_updated": 12,
    "components_updated": 3
  }
  ```
</ResponseExample>

***

## Tracking Domains

Tracking domains are separate first-party domains used for click tracking and analytics (improves ad attribution). They require Cloudflare integration.

### List Tracking Domains

```
GET /api/brands/{brand}/tracking-domains
```

### Add Tracking Domain

```
POST /api/brands/{brand}/tracking-domains
```

<ParamField type="string">
  Fully-qualified tracking domain (e.g. `track.mybrand.com`). Must be globally unique.
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/tracking-domains \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"domain": "track.mybrand.com"}'
```

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "domain": {
      "id": 9,
      "domain": "track.mybrand.com",
      "is_tracking_domain": true,
      "status": "pending-cloudflare",
      "cname_validated": false,
      "cname_validation_record": "proxy.elasticfunnels.io"
    }
  }
  ```
</ResponseExample>

### Delete Tracking Domain

```
DELETE /api/brands/{brand}/tracking-domains/{domain}
```

***

## Domain Status Values

| Status | Meaning |
| - | - |
| `pending-cname` | Waiting for CNAME DNS record |
| `pending-cloudflare` | Cloudflare hostname being provisioned |
| `validated` | DNS validated, domain active |
| `ssl-pending` | SSL certificate being issued |
| `active` | Fully configured and live |

***

## Notes

<Info>
  * Custom domains (`dedicated_domain: true`) require adding a CNAME record pointing to `proxy.elasticfunnels.io` before they can be validated
  * Platform subdomains are available instantly with no DNS changes required
  * Tracking domains go through Cloudflare provisioning automatically after creation — no manual CNAME setup needed
  * The Move endpoints transfer all page/component associations; the old domain remains but has no pages attached
</Info>


# Emails
Source: https://docs.elasticfunnels.io/api-reference/endpoints/emails

Manage email templates, access the visual builder, and retrieve automation variables

<Note>
  Email endpoints sit under `/api/brands/{brand}/emails/` with `moduleAccess:emails` middleware. Authenticate with `EF-Access-Key`.
</Note>

***

## List Emails

```
GET /api/brands/{brand}/emails
```

<ParamField type="number">
  Results per page (1–100, default: 25)
</ParamField>

<ParamField type="string">
  Search by name or subject
</ParamField>

<ParamField type="string">
  `newest`, `oldest`, `created_at`, `updated_at`
</ParamField>

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/emails \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "current_page": 1,
    "data": [
      {
        "id": 3,
        "code": "welcome-email",
        "name": "Welcome Email",
        "subject": "Welcome to our community!",
        "from_name": "Jane at MyBrand",
        "from_email": "hello@mybrand.com",
        "reply_to_email": null,
        "automation_id": 12,
        "created_at": "2024-11-01T00:00:00.000000Z"
      }
    ],
    "per_page": 25,
    "total": 7,
    "last_page": 1
  }
  ```
</ResponseExample>

***

## List Emails (Unpaginated)

Returns all emails with rendered HTML included (CSS is merged inline).

```
GET /api/brands/{brand}/emails/all
```

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "id": 3,
      "name": "Welcome Email",
      "subject": "Welcome to our community!",
      "from_name": "Jane at MyBrand",
      "from_email": "hello@mybrand.com",
      "html": "<style>/* ... */</style><html>..."
    }
  ]
  ```
</ResponseExample>

***

## Get Email

```
GET /api/brands/{brand}/emails/{email}
```

<ParamField type="string">
  Email numeric ID or `code` slug
</ParamField>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 3,
    "code": "welcome-email",
    "name": "Welcome Email",
    "subject": "Welcome to our community!",
    "preview_text": "Thanks for joining!",
    "from_name": "Jane at MyBrand",
    "from_email": "hello@mybrand.com",
    "reply_to_email": null,
    "automation_id": 12,
    "variable_scope": null,
    "html": "...",
    "css": "...",
    "inline": null,
    "screenshot": null,
    "config": {}
  }
  ```
</ResponseExample>

***

## Create Email

```
POST /api/brands/{brand}/emails
```

<ParamField type="string">
  Email template name (max 256). Defaults to `"Untitled Email"` if empty after validation.
</ParamField>

<ParamField type="string">
  Email subject line (max 512)
</ParamField>

<ParamField type="string">
  Preheader / preview text (max 512)
</ParamField>

<ParamField type="string">
  Sender display name (max 256)
</ParamField>

<ParamField type="string">
  Sender email address (max 256)
</ParamField>

<ParamField type="string">
  Reply-to address (max 256)
</ParamField>

<ParamField type="number">
  Link this email to a specific automation
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/emails \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Email",
    "subject": "Welcome to our community!",
    "from_name": "Jane at MyBrand",
    "from_email": "hello@mybrand.com",
    "automation_id": 12
  }'
```

<ResponseExample>
  ```json 200 Created theme={null}
  {
    "id": 3,
    "email": {
      "id": 3,
      "code": "welcome-email",
      "name": "Welcome Email",
      "subject": "Welcome to our community!",
      "from_name": "Jane at MyBrand",
      "from_email": "hello@mybrand.com",
      "automation_id": 12,
      "brand_id": 42,
      "created_at": "2024-12-11T10:00:00.000000Z"
    }
  }
  ```

  ```json 422 Missing required field theme={null}
  {
    "errors": {
      "name": ["The name field is required."]
    }
  }
  ```
</ResponseExample>

***

## Update Email

```
PUT /api/brands/{brand}/emails/{email}
```

<Warning>
  Use the **numeric ID** in the path when updating — using a `code` slug will cause a 404 because the `UpdateEmail` authorization query only looks up by numeric ID.
</Warning>

Same body as Create. `name` is required.

***

## Delete Email

```
DELETE /api/brands/{brand}/emails/{email}
```

<ResponseExample>
  ```json Response theme={null}
  { "success": true }
  ```
</ResponseExample>

***

## Get Builder Config

Retrieve the visual email builder config. Add `?html=1` to get the rendered HTML version.

```
GET /api/brands/{brand}/emails/{email}/builder
```

<ParamField type="boolean">
  If `1`, returns rendered HTML output instead of builder config
</ParamField>

```bash cURL — get builder config theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/emails/3/builder \
  -H "EF-Access-Key: your_api_key_here"

# Get rendered HTML
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/emails/3/builder?html=1" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Builder config response theme={null}
  {
    "assets": [ /* brand file assets */ ],
    "data": { /* email content blocks */ },
    "pageComponents": [ /* reusable components */ ],
    "fonts": [ "Montserrat", "Open Sans" ]
  }
  ```

  ```json ?html=1 response theme={null}
  {
    "html": "<!DOCTYPE html><html>...</html>",
    "config": "{ /* JSON string of config */ }",
    "inline": "<!DOCTYPE html><html>...</html>"
  }
  ```
</ResponseExample>

***

## Save Builder Config

```
POST /api/brands/{brand}/emails/{email}/builder
```

<ParamField type="string">
  Builder config as a **JSON string** (not a JSON object — must be `JSON.stringify`'d before sending)
</ParamField>

<ParamField type="string">
  Raw HTML content
</ParamField>

<ParamField type="string">
  CSS styles
</ParamField>

<ParamField type="array">
  Comments data for the email template
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/emails/3/builder \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "config": "{\"data\": {}}",
    "html": "<html>...</html>",
    "css": "body { font-family: sans-serif; }"
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 3,
    "name": "Welcome Email"
  }
  ```
</ResponseExample>

***

## Get Automation Variables

Lists the merge-tag variables available for use in this email's content, based on the automation it belongs to.

```
GET /api/brands/{brand}/emails/{email}/automation-variables
```

<ResponseExample>
  ```json Email linked to automation theme={null}
  {
    "variables": [
      { "key": "{{first_name}}", "value": "First Name", "group": "Customer" },
      { "key": "{{product_name}}", "value": "Product Name", "group": "Order" },
      { "key": "{{order_total}}", "value": "Order Total", "group": "Order" }
    ],
    "automation": {
      "id": 12,
      "title": "Welcome Email Sequence"
    },
    "context": { /* automation context */ }
  }
  ```

  ```json No automation linked theme={null}
  {
    "variables": [],
    "automation": null,
    "context": {
      "source": "none",
      "title": "No automation linked",
      "badge_label": "No automation"
    }
  }
  ```
</ResponseExample>

***

## Notes

<Info>
  * The `config` field in the builder `POST` must be sent as a **JSON string** (double-encoded), not a JSON object
  * Saving the builder config automatically regenerates inline CSS and the `inline` version of the email
  * Use numeric IDs in the URL for `PUT` / `PATCH` — `code` strings only work for `GET`, `show`, and `DELETE`
  * The `all` endpoint merges CSS inline into the HTML for direct use in rendering/preview contexts
</Info>


# File Manager
Source: https://docs.elasticfunnels.io/api-reference/endpoints/file-manager

Upload, list, rename, and delete brand media assets via API

<Note>
  All File Manager endpoints authenticate via the `EF-Access-Key` header. No session cookie or CSRF token is required.
</Note>

<Warning>
  **`POST /api/brands/{brand}/media` does not exist** (returns 404). Use [Upload File](#upload-file) (`/file-manager/upload-file`) or [Legacy upload](#legacy-upload-brand-files) (`/files/upload`) below.
</Warning>

***

## Upload File

Upload a single file to the brand's asset storage.

```
POST /api/brands/{brand}/file-manager/upload-file
```

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="file">
  Binary file (`multipart/form-data`)
</ParamField>

<ParamField type="string">
  Target subdirectory within the brand's assets folder (e.g. `media`, `media/icons`). Defaults to the root assets folder. Omit leading/trailing slashes.
</ParamField>

<ParamField type="string">
  Override the stored filename. Defaults to the original filename from the `file` field.
</ParamField>

**Accepted MIME types:** images (`image/*`), video (`video/mp4`, `video/webm`, `video/quicktime`), fonts (`font/ttf`, `font/woff`, `font/woff2`, `font/otf`), code/text (`text/css`, `text/javascript`, `application/json`, `application/javascript`).

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/file-manager/upload-file \
  -H "EF-Access-Key: your_api_key_here" \
  -F "file=@/path/to/cards.png" \
  -F "path=media" \
  -F "custom_filename=cards.png"
```

```javascript JavaScript theme={null}
const form = new FormData();
form.append('file', fileBlob, 'cards.png');
form.append('path', 'media');

const res = await fetch(
  'https://app.elasticfunnels.io/api/brands/{brand_id}/file-manager/upload-file',
  { method: 'POST', headers: { 'EF-Access-Key': 'your_api_key_here' }, body: form }
);
const result = await res.json();
// CDN URL: `https://cdn.elasticfunnels.io/{brand_id}/assets/media/${filename}`
```

<ResponseExample>
  ```json 201 Uploaded theme={null}
  {
    "HttpCode": 201,
    "Message": "File Uploaded.",
    "file_path": "ef-files/42/assets/media/cards.png"
  }
  ```
</ResponseExample>

<Note>
  The CDN URL is not included in the upload response. Derive it as:
  `https://cdn.elasticfunnels.io/{brand_id}/assets/{path}/{filename}`

  Example: `https://cdn.elasticfunnels.io/42/assets/media/cards.png`
</Note>

***

## Bulk Upload Files

Upload up to **20 files** in a single request. Each file is validated and uploaded independently — files that fail validation are reported per-file without aborting the rest.

```
POST /api/brands/{brand}/file-manager/bulk-upload-files
```

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="file[]">
  Array of files (multipart/form-data). Maximum 20 files per request.
</ParamField>

<ParamField type="string">
  Target subdirectory for all files in this batch (e.g. `media`). All files land in the same folder.
</ParamField>

<ParamField type="string[]">
  Optional array of custom filenames, positionally matched to `files[]`. Use to override individual filenames. `filenames[0]` overrides the name of `files[0]`, etc.
</ParamField>

**Per-file validation rules:**

* File must be a valid upload (not corrupted in transit)
* Maximum **10 MB** per file
* MIME type must be in the allowed list (same as single upload)

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/file-manager/bulk-upload-files \
  -H "EF-Access-Key: your_api_key_here" \
  -F "files[]=@/assets/refund-icon.png" \
  -F "files[]=@/assets/guarantee-badge.png" \
  -F "files[]=@/assets/trust-seal.svg" \
  -F "files[]=@/assets/virus.exe" \
  -F "path=media"
```

```python Python theme={null}
import requests

BRAND_ID = 42
BASE = f"https://app.elasticfunnels.io/api/brands/{BRAND_ID}/file-manager"
HEADERS = {"EF-Access-Key": "your_api_key_here"}

asset_paths = [
    "assets/universal/refund-icon.png",
    "assets/universal/guarantee-badge.png",
    "assets/universal/trust-seal.svg",
    "assets/universal/cc-icons.png",
    "assets/product/bottle-shot.png",
    "assets/product/logo.png",
]

files = [("files[]", (Path(p).name, open(p, "rb"))) for p in asset_paths]

response = requests.post(
    f"{BASE}/bulk-upload-files",
    headers=HEADERS,
    files=files,
    data={"path": "media"},
)

result = response.json()
print(f"Uploaded: {result['summary']['uploaded']}, Failed: {result['summary']['failed']}")

for f in result["files"]:
    if f["status"] == "uploaded":
        print(f"  ✓ {f['filename']} → {f['url']}")
    else:
        print(f"  ✗ {f['filename']}: {f['error']}")
```

```javascript Node.js theme={null}
import FormData from 'form-data';
import fs from 'fs';
import fetch from 'node-fetch';

const BRAND_ID = 42;
const form = new FormData();

const assets = [
  'assets/refund-icon.png',
  'assets/guarantee-badge.png',
  'assets/trust-seal.svg',
];

for (const p of assets) {
  form.append('files[]', fs.createReadStream(p));
}
form.append('path', 'media');

const res = await fetch(
  `https://app.elasticfunnels.io/api/brands/${BRAND_ID}/file-manager/bulk-upload-files`,
  { method: 'POST', headers: { 'EF-Access-Key': 'your_api_key_here', ...form.getHeaders() }, body: form }
);

const { summary, files } = await res.json();
console.log(`${summary.uploaded} uploaded, ${summary.failed} failed`);
```

<ResponseExample>
  ```json 200 Partial success theme={null}
  {
    "summary": {
      "total": 4,
      "uploaded": 3,
      "failed": 1
    },
    "files": [
      {
        "filename": "refund-icon.png",
        "status": "uploaded",
        "url": "https://cdn.elasticfunnels.io/42/assets/media/refund-icon.png",
        "size": 18432,
        "mime_type": "image/png",
        "width": 200,
        "height": 200
      },
      {
        "filename": "guarantee-badge.png",
        "status": "uploaded",
        "url": "https://cdn.elasticfunnels.io/42/assets/media/guarantee-badge.png",
        "size": 34567,
        "mime_type": "image/png",
        "width": 400,
        "height": 400
      },
      {
        "filename": "trust-seal.svg",
        "status": "uploaded",
        "url": "https://cdn.elasticfunnels.io/42/assets/media/trust-seal.svg",
        "size": 1204,
        "mime_type": "image/svg+xml",
        "width": null,
        "height": null
      },
      {
        "filename": "virus.exe",
        "status": "failed",
        "error": "MIME type \"application/x-msdownload\" is not allowed"
      }
    ]
  }
  ```

  ```json 422 Too many files theme={null}
  {
    "errors": {
      "files": ["A maximum of 20 files can be uploaded in a single request."]
    }
  }
  ```
</ResponseExample>

<Note>
  HTTP status is always **200** even when some files fail — inspect the `status` field on each entry. A `failed` entry never prevents other files from uploading.
</Note>

***

## Check File Exists

Check whether a file already exists at a given path. Useful for idempotency before uploading.

```
POST /api/brands/{brand}/file-manager/file-exists
```

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The filename only (e.g. `cards.png`)
</ParamField>

<ParamField type="string">
  The subdirectory to look in (e.g. `media`). Defaults to the root assets folder.
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/file-manager/file-exists \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"filename": "cards.png", "path": "media"}'
```

<ResponseExample>
  ```json File exists theme={null}
  {
    "exists": true
  }
  ```

  ```json File does not exist theme={null}
  {
    "exists": false
  }
  ```
</ResponseExample>

***

## Legacy: List brand files (database catalog)

`POST /api/brands/{brand}/files` returns the brand's **existing image catalog** from the database. It does **not** accept file uploads despite using POST.

```
POST /api/brands/{brand}/files
```

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/files \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "src": "https://cdn.elasticfunnels.io/42/assets/media/logo.png?t=1733846400",
        "type": "image",
        "width": 200,
        "height": 80
      }
    ]
  }
  ```
</ResponseExample>

***

## Legacy: Upload brand files

Upload one or more images to the legacy brand files store (stored under `/assets/media/` on the CDN).

```
POST /api/brands/{brand}/files/upload
```

<ParamField type="file[]">
  Image files (`multipart/form-data`). Each file must pass the `image` validation rule.
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/files/upload \
  -H "EF-Access-Key: your_api_key_here" \
  -F "files[]=@/path/to/logo.png"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "src": "https://cdn.elasticfunnels.io/42/assets/media/logo.png",
        "type": "image",
        "width": 400,
        "height": 120
      }
    ]
  }
  ```
</ResponseExample>

<Note>
  Prefer [Upload File](#upload-file) (`/file-manager/upload-file`) for new integrations — it supports paths, custom filenames, and more MIME types.
</Note>

***

## List Files

Browse the raw Bunny CDN storage directory for the brand. Returns files and folders from storage directly (not the database). Sorted newest-first; folders are listed before files.

```
GET /api/brands/{brand}/file-manager/files
```

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Comma-separated list of extensions to filter by (e.g. `png,jpg,svg`)
</ParamField>

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/file-manager/files" \
  -H "EF-Access-Key: your_api_key_here"
```

```bash cURL (filter by extension) theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/file-manager/files?extensions=png,jpg,svg" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "ObjectName": "media",
      "IsDirectory": true,
      "type": "folder",
      "BrowsePath": "media/",
      "Length": "0 KB",
      "sizeBytes": 0,
      "LastChanged": "2024-12-10T14:00:00Z"
    },
    {
      "ObjectName": "cards.png",
      "IsDirectory": false,
      "type": "file",
      "BrowsePath": "media/cards.png",
      "src": "https://cdn.elasticfunnels.io/42/assets/media/cards.png",
      "Length": "33.76 KB",
      "sizeBytes": 34567,
      "width": 400,
      "height": 400,
      "srcset": "https://cdn.elasticfunnels.io/42/assets/media/cards.png?width=200 200w, ...",
      "sizes": "(max-width: 640px) 100vw, ...",
      "LastChanged": "2024-12-10T14:01:00Z"
    }
  ]
  ```
</ResponseExample>

***

## List Assets

Return all brand assets tracked in the **database**. Unlike [List Files](#list-files) which reads from CDN storage, this returns structured records including file IDs and paths — useful for linking uploaded files to other API operations.

```
GET /api/brands/{brand}/file-manager/assets
```

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  ISO 8601 timestamp — only return assets updated after this date (e.g. `2024-12-01T00:00:00Z`). Useful for incremental sync.
</ParamField>

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/file-manager/assets" \
  -H "EF-Access-Key: your_api_key_here"
```

```bash cURL (incremental sync) theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/file-manager/assets?updated_after=2024-12-01T00:00:00Z" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "id": 101,
      "file_name": "cards.png",
      "file_path": "media/cards.png",
      "updated_at": "2024-12-10T14:01:00+00:00"
    },
    {
      "id": 102,
      "file_name": "guarantee-badge.png",
      "file_path": "media/guarantee-badge.png",
      "updated_at": "2024-12-10T14:02:00+00:00"
    }
  ]
  ```
</ResponseExample>

***

## Delete File

Delete a file or folder from asset storage. The corresponding database record is also removed.

```
POST /api/brands/{brand}/file-manager/delete-file
```

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Path of the file to delete, relative to the brand's assets folder (e.g. `media/cards.png`). No leading slash.
</ParamField>

<Warning>
  Deletion is permanent. The following paths are **protected** and cannot be deleted via API:

  * `media` (the folder itself)
  * `products` and anything inside it (used in product forms)
  * Empty path (root assets folder)
</Warning>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/file-manager/delete-file \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"path": "media/old-badge.png"}'
```

<ResponseExample>
  ```json Success theme={null}
  {
    "HttpCode": 200,
    "Message": "File Deleted Successfully."
  }
  ```

  ```json Protected path theme={null}
  {
    "errors": {
      "message": "Cannot delete media folder"
    }
  }
  ```

  ```json Out-of-bounds path theme={null}
  {
    "errors": {
      "message": "Invalid path: Cannot access files outside of brand assets folder"
    }
  }
  ```

  ```json File not found theme={null}
  {
    "errors": {
      "message": "File not found"
    }
  }
  ```
</ResponseExample>

***

## Rename File

Rename a file in asset storage. Because Bunny CDN does not support atomic rename, this downloads the original content, uploads it under the new name, and deletes the original. The database record is updated automatically.

```
POST /api/brands/{brand}/file-manager/rename-file
```

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Current path of the file relative to the brand's assets folder (e.g. `media/old-name.png`). No leading slash.
</ParamField>

<ParamField type="string">
  New filename only — not a path (e.g. `new-name.png`). Must not contain `/` or `\`.
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/file-manager/rename-file \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"path": "media/old-name.png", "new_name": "cards.png"}'
```

<ResponseExample>
  ```json Success theme={null}
  {
    "success": true,
    "old_path": "media/old-name.png",
    "new_path": "media/cards.png",
    "url": "https://cdn.elasticfunnels.io/42/assets/media/cards.png"
  }
  ```

  ```json File not found theme={null}
  {
    "errors": {
      "message": "File not found"
    }
  }
  ```

  ```json Invalid new_name theme={null}
  {
    "errors": {
      "new_name": ["new_name must be a filename only, not a path."]
    }
  }
  ```
</ResponseExample>

<Note>
  **Rename folder** (`POST …/file-manager/rename-folder`) is not yet supported via the API. It returns `501 Not Implemented`. Use the File Manager UI to rename folders.
</Note>

***

## Create Folder

Create a new folder inside the brand's asset storage.

```
POST /api/brands/{brand}/file-manager/create-folder
```

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Parent directory for the new folder (e.g. `media`)
</ParamField>

<ParamField type="string">
  Folder name. Must match `^[a-z0-9_-]+$` — lowercase letters, numbers, hyphens, underscores only.
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/file-manager/create-folder \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"path": "media", "name": "product-shots"}'
```

<ResponseExample>
  ```json Success theme={null}
  {
    "message": "Folder created successfully."
  }
  ```

  ```json Already exists theme={null}
  {
    "errors": {
      "name": ["Folder already exists"]
    }
  }
  ```

  ```json Invalid name theme={null}
  {
    "errors": {
      "name": ["Folder name can only contain letters, numbers, underscores, and hyphens."]
    }
  }
  ```
</ResponseExample>

***

## Automated Product Provisioning

Complete example: bulk-upload all universal + product-specific assets for a new product, then idempotently re-run without re-uploading existing files.

```python Python theme={null}
import requests
from pathlib import Path

BRAND_ID = 42
API_KEY = "your_api_key_here"
BASE = f"https://app.elasticfunnels.io/api/brands/{BRAND_ID}/file-manager"
CDN = f"https://cdn.elasticfunnels.io/{BRAND_ID}/assets"
HEADERS = {"EF-Access-Key": API_KEY}


def bulk_upload(local_paths: list[Path], folder: str) -> dict[str, str]:
    """Upload a batch; skip files that already exist. Returns {filename: cdn_url}."""

    # Check which already exist
    to_upload = []
    urls = {}
    for p in local_paths:
        r = requests.post(
            f"{BASE}/file-exists",
            headers=HEADERS,
            json={"filename": p.name, "path": folder},
        )
        if r.json().get("exists"):
            print(f"  skip  {p.name} (already on CDN)")
            urls[p.name] = f"{CDN}/{folder}/{p.name}"
        else:
            to_upload.append(p)

    if not to_upload:
        return urls

    # Bulk upload the rest
    files = [("files[]", (p.name, p.open("rb"))) for p in to_upload]
    r = requests.post(
        f"{BASE}/bulk-upload-files",
        headers=HEADERS,
        files=files,
        data={"path": folder},
    )
    r.raise_for_status()

    for entry in r.json()["files"]:
        if entry["status"] == "uploaded":
            print(f"  ✓  {entry['filename']}")
            urls[entry["filename"]] = entry["url"]
        else:
            print(f"  ✗  {entry['filename']}: {entry['error']}")

    return urls


UNIVERSAL = [
    Path("assets/universal/refund-icon.png"),
    Path("assets/universal/guarantee-badge.png"),
    Path("assets/universal/trust-seal.svg"),
    Path("assets/universal/cc-icons.png"),
]

PRODUCT = [
    Path("assets/product/bottle-shot.png"),
    Path("assets/product/logo.png"),
]

print("Uploading universal assets…")
universal_urls = bulk_upload(UNIVERSAL, "media")

print("Uploading product assets…")
product_urls = bulk_upload(PRODUCT, "media/products")

all_urls = {**universal_urls, **product_urls}
print(f"\nDone. {len(all_urls)} assets ready.")
```


# Funnels
Source: https://docs.elasticfunnels.io/api-reference/endpoints/funnels

Manage sales funnels

## List All Funnels

Retrieve all funnels for a project.

<ParamField type="string">
  The brand/project ID
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/funnels/all
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/funnels/all \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": 1,
        "name": "Main Sales Funnel",
        "status": "active",
        "pages_count": 4,
        "created_at": "2024-01-15T10:30:00.000000Z"
      }
    ]
  }
  ```
</ResponseExample>

***

## Get Funnel Details

Retrieve details about a specific funnel.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The funnel ID
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/funnels/{funnel}
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/funnels/{funnel_id} \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 1,
    "name": "Main Sales Funnel",
    "status": "active",
    "pages": [
      {
        "id": 1,
        "name": "Landing Page",
        "type": "landing",
        "order": 1
      },
      {
        "id": 2,
        "name": "Checkout",
        "type": "checkout",
        "order": 2
      },
      {
        "id": 3,
        "name": "Upsell",
        "type": "upsell",
        "order": 3
      },
      {
        "id": 4,
        "name": "Thank You",
        "type": "thankyou",
        "order": 4
      }
    ],
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-12-10T08:20:00.000000Z"
  }
  ```
</ResponseExample>

***

## Create Funnel

Create a new funnel.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Funnel name
</ParamField>

<ParamField type="string">
  Funnel status: `active` or `inactive` (default: `active`)
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/funnels
```

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/funnels \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Funnel",
    "status": "active"
  }'
```

***

## Update Funnel

Update an existing funnel.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The funnel ID
</ParamField>

```bash Request theme={null}
PUT /api/brands/{brand}/funnels/{funnel}
```

```bash cURL theme={null}
curl -X PUT https://app.elasticfunnels.io/api/brands/{brand_id}/funnels/{funnel_id} \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Funnel Name"
  }'
```

***

## Delete Funnel

Delete a funnel.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The funnel ID
</ParamField>

```bash Request theme={null}
DELETE /api/brands/{brand}/funnels/{funnel}
```

```bash cURL theme={null}
curl -X DELETE https://app.elasticfunnels.io/api/brands/{brand_id}/funnels/{funnel_id} \
  -H "EF-Access-Key: your_api_key_here"
```

***

## Clone Funnel

Create a copy of an existing funnel with all its pages.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The funnel ID to clone
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/funnels/{funnel}/clone
```

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/funnels/{funnel_id}/clone \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 2,
    "name": "Copy of Main Sales Funnel",
    "status": "inactive",
    "pages_count": 4,
    "created_at": "2024-12-10T16:00:00.000000Z"
  }
  ```
</ResponseExample>


# Pages
Source: https://docs.elasticfunnels.io/api-reference/endpoints/pages

Manage landing pages and retrieve page information

## List All Pages

Retrieve all pages for a project.

<ParamField type="string">
  The brand/project ID
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/pages/all
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/pages/all \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": 1,
        "name": "Landing Page",
        "slug": "landing-page",
        "status": "active",
        "type": "landing",
        "created_at": "2024-01-15T10:30:00.000000Z"
      },
      {
        "id": 2,
        "name": "Thank You Page",
        "slug": "thank-you",
        "status": "active",
        "type": "thankyou",
        "created_at": "2024-01-16T11:20:00.000000Z"
      }
    ]
  }
  ```
</ResponseExample>

***

## Get Page Details

Retrieve details about a specific page.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The page ID
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/pages/{page}
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/pages/{page_id} \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 1,
    "name": "Landing Page",
    "slug": "landing-page",
    "status": "active",
    "type": "landing",
    "meta_title": "Amazing Product",
    "meta_description": "Get your product now",
    "url": "https://yourdomain.com/landing-page",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-12-10T08:20:00.000000Z"
  }
  ```
</ResponseExample>

***

## Create Page

Create a new page.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Page title
</ParamField>

<ParamField type="string">
  Page builder type: must be `editor` (optional if `html` is provided, required otherwise)
</ParamField>

<ParamField type="string">
  URL-friendly slug (optional, auto-generated if not provided)
</ParamField>

<ParamField type="string">
  Page status: `published`, `draft`, `offline`, `imported` (default: `draft`)
</ParamField>

<ParamField type="string">
  Raw HTML content (automatically sets page\_type to `editor`). If this HTML contains `<inline-split-test>`, the Pages API stores that source markup as provided.
</ParamField>

<ParamField type="number">
  Custom domain ID (optional)
</ParamField>

<ParamField type="number">
  Funnel ID to associate with (optional)
</ParamField>

<ParamField type="number">
  Folder ID to organize page (optional)
</ParamField>

<ParamField type="boolean">
  Set as index page (default: false)
</ParamField>

<ParamField type="string">
  Custom CSS styles
</ParamField>

<ParamField type="string">
  Template type: `nutra-prelander`, `nutra-advertorial`, `leadgen`, `webinar-registration`
</ParamField>

<ParamField type="string">
  Template ID to use (optional)
</ParamField>

<ParamField type="string">
  SEO meta title
</ParamField>

<ParamField type="string">
  Alternative title when tab is not focused
</ParamField>

<ParamField type="string">
  SEO meta description
</ParamField>

<ParamField type="boolean">
  Require user login to access
</ParamField>

<ParamField type="boolean">
  Require password to access
</ParamField>

<ParamField type="string">
  Page password (required if requires\_password is true)
</ParamField>

<ParamField type="string">
  URL to redirect to
</ParamField>

<ParamField type="string">
  Google Analytics measurement ID
</ParamField>

<ParamField type="string">
  Meta (Facebook) Pixel ID
</ParamField>

<ParamField type="string">
  Custom JavaScript code
</ParamField>

<ParamField type="boolean">
  Mark as upsell page
</ParamField>

<ParamField type="boolean">
  Show affiliate tracking pixels
</ParamField>

<ParamField type="boolean">
  Disable default tracking scripts
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/pages
```

### Create Basic Page

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/pages \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Landing Page",
    "slug": "new-landing",
    "page_type": "editor",
    "status": "published"
  }'
```

### Create Page with HTML

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/pages \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Custom HTML Page",
    "slug": "custom-page",
    "status": "published",
    "html": "<!DOCTYPE html><html><head><title>My Page</title></head><body><h1>Hello World</h1></body></html>",
    "css": "body { background: #f5f5f5; font-family: Arial, sans-serif; }"
  }'
```

<Note>
  * When you provide `html` in the request, `page_type` is automatically set to `editor`, so you don't need to specify it
  * The API only supports **editor** type pages. The visual drag-and-drop builder is available only through the web dashboard
  * On update, providing `html` will automatically convert the page to `editor` type if it isn't already
  * If your `html` contains `<inline-split-test>`, the create/update response returns stored source HTML, not the runtime-resolved winning variant HTML
</Note>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 3,
    "title": "New Landing Page",
    "slug": "new-landing",
    "status": "published",
    "page_type": "editor",
    "url": "https://yourdomain.com/new-landing",
    "created_at": "2024-12-10T15:45:00.000000Z"
  }
  ```
</ResponseExample>

### Inline Split Test HTML in Pages API

When you send `<inline-split-test>` markup through `POST /api/brands/{brand}/pages` or `PUT /api/brands/{brand}/pages/{page}`:

* The endpoint stores the full source HTML you send in `html`
* The response does **not** replace the tag with the chosen runtime variant
* The public Pages API does **not** inject the auto-managed `id` attribute during create/update

Example request body:

```json theme={null}
{
  "title": "Split Test Page",
  "slug": "split-test-page",
  "status": "published",
  "html": "<inline-split-test name=\"Headline Test\"><variant name=\"control\" weight=\"70\"><h1>Original Headline</h1></variant><variant name=\"challenger\" weight=\"30\"><h1>New Headline</h1></variant></inline-split-test>"
}
```

Example create response shape:

```json Response theme={null}
{
  "page": {
    "id": 12,
    "title": "Split Test Page",
    "slug": "split-test-page",
    "status": "published",
    "page_type": "editor",
    "html": "<inline-split-test name=\"Headline Test\"><variant name=\"control\" weight=\"70\"><h1>Original Headline</h1></variant><variant name=\"challenger\" weight=\"30\"><h1>New Headline</h1></variant></inline-split-test>"
  }
}
```

Runtime rendering is different from the API response. When a visitor loads the page, the server replaces the entire block with the chosen variant wrapped like this:

```html theme={null}
<div data-sid="[split_test_id]" data-cid="[variant_code]">
  <!-- Full HTML of the chosen variant -->
</div>
```

<Warning>
  If you use a save flow that returns normalized inline split test HTML with a server-generated `id`, replace your local/source HTML with that returned HTML before the next update. This only matters when your next request includes `html` again. If `html` is omitted because nothing changed, the existing stored HTML stays unchanged. Re-sending the original `<inline-split-test>` markup without the injected `id` in a later `html` update can cause the server to create a new split test record on every save.
</Warning>

***

## Update Page

Update an existing page. Only include the fields you want to change.

<Warning>
  **Common causes of errors on PUT/PATCH:**

  | Symptom | Cause | Fix |
  | - | - | - |
  | `422` with `title is required` | `title` is always required by the validator, even if you're only changing HTML | Always include `"title"` in the body |
  | `401` / redirect to login | Missing or invalid `EF-Access-Key` header, or key doesn't belong to this brand | Check the header name (`EF-Access-Key`) and value |
  | `403` module access | Brand user role doesn't have `pages` access | Update role permissions in Project Settings |
  | Slug `422` uniqueness error | Provided `slug` already exists for another page on the same domain | Choose a unique slug or omit it |
</Warning>

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The page ID
</ParamField>

<ParamField type="string">
  Page title
</ParamField>

<ParamField type="string">
  URL-friendly slug
</ParamField>

<ParamField type="string">
  Page status: `published`, `draft`, `offline`, `imported`
</ParamField>

<ParamField type="number">
  Custom domain ID
</ParamField>

<ParamField type="number">
  Folder ID to organize page
</ParamField>

<ParamField type="boolean">
  Set as index page
</ParamField>

<ParamField type="string">
  Raw HTML content (automatically sets page\_type to `editor`). If this HTML contains `<inline-split-test>`, the Pages API stores that source markup as provided.
</ParamField>

<ParamField type="string">
  Custom CSS styles
</ParamField>

<ParamField type="string">
  SEO meta title
</ParamField>

<ParamField type="string">
  Alternative title when tab is not focused
</ParamField>

<ParamField type="string">
  SEO meta description
</ParamField>

<ParamField type="boolean">
  Require user login to access
</ParamField>

<ParamField type="boolean">
  Require password to access
</ParamField>

<ParamField type="string">
  Page password
</ParamField>

<ParamField type="string">
  URL to redirect to
</ParamField>

<ParamField type="boolean">
  Disable right-click on page
</ParamField>

<ParamField type="boolean">
  Prevent search engine indexing
</ParamField>

<ParamField type="boolean">
  Only accessible through funnel flow
</ParamField>

<ParamField type="string">
  Google Analytics measurement ID
</ParamField>

<ParamField type="string">
  Meta (Facebook) Pixel ID
</ParamField>

<ParamField type="string">
  Custom header code
</ParamField>

<ParamField type="string">
  Custom JavaScript code (must be valid script tags only)
</ParamField>

<ParamField type="boolean">
  Mark as upsell page
</ParamField>

<ParamField type="boolean">
  Show affiliate tracking pixels
</ParamField>

<ParamField type="boolean">
  Disable default tracking scripts
</ParamField>

```bash Request theme={null}
PUT /api/brands/{brand}/pages/{page}
```

### Update Basic Information

```bash cURL theme={null}
curl -X PUT https://app.elasticfunnels.io/api/brands/{brand_id}/pages/{page_id} \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Page Name",
    "status": "published"
  }'
```

### Update page title and status

```bash cURL theme={null}
curl -X PUT https://app.elasticfunnels.io/api/brands/{brand_id}/pages/{page_id} \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Page Name",
    "status": "published"
  }'
```

### Update HTML content

```bash cURL theme={null}
curl -X PUT https://app.elasticfunnels.io/api/brands/{brand_id}/pages/{page_id} \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Custom Page",
    "html": "<!DOCTYPE html><html><body><h1>Updated Content</h1></body></html>",
    "css": "body { font-family: Arial; }"
  }'
```

<Note>
  Providing `html` automatically converts the page to `editor` type if it isn't already.
</Note>

### Update SEO settings

```bash cURL theme={null}
curl -X PUT https://app.elasticfunnels.io/api/brands/{brand_id}/pages/{page_id} \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Landing Page",
    "seo_title": "Best Product Ever - Buy Now",
    "seo_description": "Discover the amazing benefits of our product",
    "prevent_indexing": false
  }'
```

<ResponseExample>
  ```json 200 Updated theme={null}
  {
    "id": 3,
    "brand_id": 42,
    "title": "My Custom Page",
    "slug": "my-custom-page",
    "status": "published",
    "page_type": "editor",
    "html": "<!DOCTYPE html><html><body><h1>Updated Content</h1></body></html>",
    "css": "body { font-family: Arial; }",
    "seo_title": "My Custom Page",
    "seo_description": null,
    "domain_id": null,
    "folder_id": null,
    "updated_at": "2024-12-11T09:15:00.000000Z"
  }
  ```

  ```json 422 Missing title theme={null}
  {
    "errors": {
      "title": ["The title field is required."]
    }
  }
  ```

  ```json 422 Duplicate slug theme={null}
  {
    "errors": {
      "slug": ["The slug has already been taken."]
    }
  }
  ```

  ```json 401 Bad API key theme={null}
  {
    "message": "Invalid API key or brand access denied"
  }
  ```
</ResponseExample>

***

## Page Types and Fields

### API Page Type: Editor Only

<Info>
  The API only supports creating **editor** pages. The visual drag-and-drop builder is only available through the web dashboard interface.
</Info>

**Editor Pages** allow direct HTML/CSS editing through the API:

* `html` - Raw HTML content
* `css` - Custom CSS styles
* `page_type` - Must be `editor` (or automatically set when `html` is provided)

### Automatic Editor Type Assignment

When you provide the `html` field in a create or update request, the page is automatically set to `editor` type, even if you don't specify `page_type`.

```json theme={null}
{
  "title": "My Page",
  "html": "<html>...</html>"
  // page_type is automatically set to "editor"
}
```

### Update Behavior

When updating pages:

* **Only provided fields are updated** - omitted fields remain unchanged
* `html` field is updated if provided in the request
* `css` field is updated if provided in the request
* Providing `html` will automatically set/update `page_type` to `editor`
* Empty strings will clear the field value

### Custom JavaScript Validation

The `custom_javascript` field must contain only valid `<script>` tags. HTML comments and `<noscript>` tags are allowed.

```html theme={null}
<!-- Valid -->
<script>
  console.log('Hello World');
</script>

<!-- Invalid - contains non-script elements -->
<div>Some content</div>
<script>console.log('test');</script>
```

***

## Delete Page

Delete a page.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The page ID
</ParamField>

```bash Request theme={null}
DELETE /api/brands/{brand}/pages/{page}
```

```bash cURL theme={null}
curl -X DELETE https://app.elasticfunnels.io/api/brands/{brand_id}/pages/{page_id} \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "message": "Page deleted successfully"
  }
  ```
</ResponseExample>

***

## Plan Limits and Errors

When creating pages, the API checks against your plan limits:

### Plan Limit Exceeded Error

```json theme={null}
{
  "error": "Plan limit exceeded",
  "plan_error": {
    "type": "plan_limit_exceeded",
    "feature": "pages",
    "message": "You have reached the maximum number of pages (10) allowed for your plan.",
    "current_count": 10,
    "limit": 10,
    "plan_name": "Starter",
    "upgrade_info": {
      "required_plan": "Professional",
      "feature_description": "Unlimited pages"
    }
  },
  "errors": {
    "title": ["You have reached the maximum number of pages (10) allowed for your plan. Please upgrade to create more pages."]
  }
}
```

**Status Code:** `422 Unprocessable Entity`

### Plan Feature Not Available Error

```json theme={null}
{
  "error": "Plan limit exceeded",
  "plan_error": {
    "type": "plan_upgrade_required",
    "feature": "pages",
    "message": "Your current plan does not allow creating pages.",
    "plan_name": "Free Trial",
    "upgrade_info": {
      "required_plan": "Starter",
      "feature_description": "Create landing pages"
    }
  },
  "errors": {
    "title": ["Your current plan does not allow creating pages. Please upgrade to access this feature."]
  }
}
```

**Status Code:** `422 Unprocessable Entity`

***

## Clone Page

Create a copy of an existing page.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The page ID to clone
</ParamField>

<ParamField type="string">
  Name for the cloned page (optional, defaults to "Copy of \[original name]")
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/pages/{page}/clone
```

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/pages/{page_id}/clone \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cloned Landing Page"
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 4,
    "name": "Cloned Landing Page",
    "slug": "cloned-landing-page",
    "status": "inactive",
    "type": "landing",
    "created_at": "2024-12-10T16:00:00.000000Z"
  }
  ```
</ResponseExample>


# Products
Source: https://docs.elasticfunnels.io/api-reference/endpoints/products

Manage products and SKUs

## List All Products

Retrieve all products for a project with pagination.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="number">
  Page number for pagination (default: 1)
</ParamField>

<ParamField type="number">
  Number of results per page (default: 25)
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/products
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/products \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "current_page": 1,
    "data": [
      {
        "id": 2,
        "brand_id": 1,
        "code": "glucotil",
        "type": "physical",
        "title": "1 Bottle",
        "checkout_title": null,
        "price": 69,
        "retail_price": 99,
        "image": "https://storage.googleapis.com/asper-digital/1/1-bottle.png",
        "image_link": "https://storage.googleapis.com/asper-digital/1/1-bottle.png",
        "units": 1,
        "sku": "prod1",
        "classification": "main",
        "product_files": [],
        "unit_cost": null,
        "unit_weight_oz": null,
        "fulfillment_cost": null,
        "packaging_cost": null,
        "fuel_surcharge_cost": null,
        "cogs": null,
        "custom_attributes": null,
        "merchant_product_ids": [],
        "physical_units_per_product": null,
        "fulfillment_multiply_sku": 0,
        "sku_category": null,
        "sku_subcategory": null,
        "product_specifications": null,
        "shipping_profile_id": null,
        "is_subscription": false,
        "subscription_frequency": null,
        "subscription_frequency_unit": null,
        "subscription_trial_days": null,
        "subscription_first_charge_free": false,
        "average_shipping_cost": null,
        "bonuses": []
      }
    ],
    "first_page_url": "https://app.elasticfunnels.io/api/brands/1/products?page=1",
    "from": 1,
    "last_page": 1,
    "last_page_url": "https://app.elasticfunnels.io/api/brands/1/products?page=1",
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://app.elasticfunnels.io/api/brands/1/products?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "next_page_url": null,
    "path": "https://app.elasticfunnels.io/api/brands/1/products",
    "per_page": 25,
    "prev_page_url": null,
    "to": 8,
    "total": 8
  }
  ```
</ResponseExample>

***

## List All Products (Unpaginated)

Get all products without pagination for dropdown lists.

<ParamField type="string">
  The brand/project ID
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/products/all
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/products/all \
  -H "EF-Access-Key: your_api_key_here"
```

***

## Get Product Details

Retrieve details about a specific product.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The product ID
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/products/{product}
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/products/2 \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 2,
    "brand_id": 1,
    "code": "glucotil",
    "type": "physical",
    "title": "1 Bottle",
    "checkout_title": null,
    "price": 69,
    "retail_price": 99,
    "image": "https://storage.googleapis.com/asper-digital/1/1-bottle.png",
    "image_link": "https://storage.googleapis.com/asper-digital/1/1-bottle.png",
    "units": 1,
    "sku": "prod1",
    "classification": "main",
    "product_files": [],
    "unit_cost": null,
    "unit_weight_oz": null,
    "fulfillment_cost": null,
    "packaging_cost": null,
    "fuel_surcharge_cost": null,
    "cogs": null,
    "custom_attributes": null,
    "merchant_product_ids": {},
    "physical_units_per_product": null,
    "fulfillment_multiply_sku": 0,
    "sku_category": null,
    "sku_subcategory": null,
    "product_specifications": null,
    "shipping_profile_id": null,
    "is_subscription": false,
    "subscription_frequency": null,
    "subscription_frequency_unit": null,
    "subscription_trial_days": null,
    "subscription_first_charge_free": false,
    "average_shipping_cost": null,
    "bonuses": []
  }
  ```
</ResponseExample>

***

## Product Fields Reference

<AccordionGroup>
  <Accordion title="Basic Information">
    * `code` - Unique product code/identifier
    * `title` - Product display name
    * `checkout_title` - Alternative title for checkout (optional)
    * `type` - Product type: `physical`, `digital`
    * `classification` - Product classification: `main`, `upsell`, `downsell`, `bump`, `bonus`
  </Accordion>

  <Accordion title="Pricing">
    * `price` - Selling price (in currency units)
    * `retail_price` - Suggested retail/original price
    * `units` - Number of units included
  </Accordion>

  <Accordion title="Inventory & Fulfillment">
    * `sku` - Stock Keeping Unit identifier
    * `unit_cost` - Cost per unit
    * `unit_weight_oz` - Weight per unit in ounces
    * `fulfillment_cost` - Cost to fulfill the order
    * `packaging_cost` - Packaging cost
    * `fuel_surcharge_cost` - Fuel surcharge
    * `cogs` - Cost of Goods Sold
    * `physical_units_per_product` - Physical units per product
    * `fulfillment_multiply_sku` - Multiply fulfillment by SKU quantity
    * `average_shipping_cost` - Average shipping cost
  </Accordion>

  <Accordion title="Media">
    * `image` - Product image URL
    * `image_link` - Full URL to product image
    * `product_files` - Array of downloadable files attached to the product
  </Accordion>

  <Accordion title="Subscription Products">
    * `is_subscription` - Whether this is a subscription product
    * `subscription_frequency` - Billing frequency (e.g., 1, 2, 3)
    * `subscription_frequency_unit` - Unit: `day`, `week`, `month`, `year`
    * `subscription_trial_days` - Number of trial days
    * `subscription_first_charge_free` - Whether first charge is free
  </Accordion>

  <Accordion title="Additional">
    * `custom_attributes` - Array of custom key-value pairs
    * `merchant_product_ids` - Object mapping merchant names to product IDs
    * `product_specifications` - Array of product specifications
    * `shipping_profile_id` - Associated shipping profile
    * `sku_category` - SKU category
    * `sku_subcategory` - SKU subcategory
    * `bonuses` - Array of bonus products associated with this product
  </Accordion>
</AccordionGroup>

***

## Create Product

Create a new product.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Unique product code
</ParamField>

<ParamField type="string">
  Product title
</ParamField>

<ParamField type="number">
  Product price
</ParamField>

<ParamField type="string">
  Product type: `physical` or `digital`
</ParamField>

<ParamField type="string">
  Classification: `main`, `upsell`, `downsell`, `bump`, or `bonus`
</ParamField>

<ParamField type="number">
  Retail/original price
</ParamField>

<ParamField type="number">
  Number of units
</ParamField>

<ParamField type="string">
  Stock Keeping Unit
</ParamField>

<ParamField type="file">
  Product image file (`multipart/form-data` only). Must be an uploaded image file — **not** a JSON URL string. Omit from JSON-only creates; upload via [File Manager](/api-reference/endpoints/file-manager#upload-file) and reference the CDN URL in HTML, or send `image` on a multipart create request.
</ParamField>

<ParamField type="boolean">
  Whether this is a subscription product
</ParamField>

<ParamField type="number">
  Billing frequency (required if is\_subscription is true)
</ParamField>

<ParamField type="string">
  Frequency unit: `day`, `week`, `month`, `year`
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/products
```

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/products \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "product_123",
    "title": "Premium Product",
    "price": 49.99,
    "retail_price": 79.99,
    "type": "physical",
    "classification": "main",
    "units": 1,
    "sku": "PREM-001"
  }'
```

### Subscription Product Example

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/products \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "monthly_subscription",
    "title": "Monthly Subscription",
    "price": 29.99,
    "type": "physical",
    "classification": "main",
    "is_subscription": true,
    "subscription_frequency": 1,
    "subscription_frequency_unit": "month",
    "subscription_trial_days": 14,
    "subscription_first_charge_free": true
  }'
```

### Create with image (multipart)

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/products \
  -H "EF-Access-Key: your_api_key_here" \
  -F "code=product_123" \
  -F "title=Premium Product" \
  -F "price=49.99" \
  -F "type=physical" \
  -F "classification=main" \
  -F "image=@/path/to/bottle.png"
```

<Note>
  Sending `"image": "https://..."` in a JSON body fails validation (`422`) or is ignored — the API expects a file upload for the `image` field.
</Note>

***

## Update Product

Update an existing product. Authenticate with `EF-Access-Key` on every request.

<Note>
  Both **PUT** and **POST** are supported for the same update handler. If PUT returns a redirect to login, use **POST** with the same URL and body.
</Note>

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The product ID
</ParamField>

<ParamField type="string">
  Product title (use `title`, not `name`)
</ParamField>

<ParamField type="number">
  Product price
</ParamField>

<ParamField type="file">
  Replace product image (`multipart/form-data` file upload, same rules as create)
</ParamField>

```bash Request theme={null}
PUT /api/brands/{brand}/products/{product}
```

Alternative (same handler):

```
POST /api/brands/{brand}/products/{product}
```

```bash cURL (PUT) theme={null}
curl -X PUT https://app.elasticfunnels.io/api/brands/{brand_id}/products/{product_id} \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Product Title",
    "price": 59.99
  }'
```

```bash cURL (POST — preferred if PUT redirects) theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/products/{product_id} \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Product Title",
    "price": 59.99
  }'
```

<ResponseExample>
  ```json 200 Updated theme={null}
  {
    "id": 2,
    "title": "Updated Product Title",
    "code": "glucotil",
    "price": 59.99,
    "brand_id": 42
  }
  ```
</ResponseExample>

***

## Delete Product

Delete a product.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The product ID
</ParamField>

```bash Request theme={null}
DELETE /api/brands/{brand}/products/{product}
```

```bash cURL theme={null}
curl -X DELETE https://app.elasticfunnels.io/api/brands/{brand_id}/products/{product_id} \
  -H "EF-Access-Key: your_api_key_here"
```

***

## Clone Product

Create a copy of an existing product.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The product ID to clone
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/products/{product}/clone
```

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/products/2/clone \
  -H "EF-Access-Key: your_api_key_here"
```

***

## Product Classifications

| Classification | Description | Usage |
| - | - | - |
| `main` | Main product offer | Primary product in funnel |
| `upsell` | Upsell product | Offered after initial purchase |
| `downsell` | Downsell product | Offered if upsell is declined |
| `bump` | Order bump | Checkbox add-on at checkout |
| `bonus` | Bonus product | Free gift or bonus item |

***

## Product Bonuses

Products can have associated bonus products. The `bonuses` array contains bonus product relationships:

```json theme={null}
{
  "bonuses": [
    {
      "bonus_product_id": 23,
      "product_id": 3,
      "brand_id": 1
    },
    {
      "bonus_product_id": 24,
      "product_id": 3,
      "brand_id": 1
    }
  ]
}
```

When a customer purchases a product with bonuses, they automatically receive the bonus products.

***

## Downloadable Files

Digital downloads and bonus downloads are stored in `product_files`.

Each file row can include:

* `purpose` - `digital` or `bonus`
* `title` - Optional display title
* `description` - Optional description shown in customer-facing download UIs
* `image` - Optional thumbnail/cover image URL for this file
* `file` - File URL
* `kind` - Coarse classification derived from the file extension and `metadata.mime_type`. One of `audio`, `video`, `document`, `image`, `archive`, `file`. Lets clients branch on file type without re-parsing the URL.
* `is_primary` - Marks the default file for that purpose
* `sort_order` - Controls display order
* `metadata` - Public file metadata. Only the following fields are exposed:

  * `mime_type` - MIME type of the file (e.g. `"audio/mpeg"`, `"application/pdf"`)
  * `size` - Size in bytes
  * `checksum` - Optional checksum recorded at upload (may be `null`)
  * `extension` - Lowercase extension without the dot (e.g. `"pdf"`, `"mp3"`). Derived from the file URL when possible, with a small mime-type fallback for opaque/signed URLs. Empty string when neither source can produce one.

  Internal storage pointers (`provider`, `storage_path`, `brand_file_id`) are intentionally not returned.

```json theme={null}
{
  "product_files": [
    {
      "purpose": "digital",
      "title": "Quick Start Guide",
      "description": "PDF onboarding guide",
      "image": "https://cdn.example.com/guide-cover.jpg",
      "file": "https://cdn.example.com/guide.pdf",
      "kind": "document",
      "is_primary": true,
      "sort_order": 0,
      "metadata": {
        "mime_type": "application/pdf",
        "size": 182734,
        "checksum": null,
        "extension": "pdf"
      }
    },
    {
      "purpose": "bonus",
      "title": "Bonus Audio",
      "file": "https://cdn.example.com/bonus.mp3",
      "kind": "audio",
      "is_primary": true,
      "sort_order": 0,
      "metadata": {
        "mime_type": "audio/mpeg",
        "size": 10876045,
        "checksum": null,
        "extension": "mp3"
      }
    }
  ]
}
```

Use bonus-product relationships for entitlement, and use `product_files` for the actual downloadable assets those products expose.

***

## Custom Attributes

Products support custom key-value attributes for flexibility:

```json theme={null}
{
  "custom_attributes": [
    {
      "key": "download",
      "value": "https://example.com/download"
    },
    {
      "key": "access_code",
      "value": "ABC123"
    }
  ]
}
```

Common uses:

* Download links for digital products
* Access codes for member areas
* Special instructions
* Custom tracking parameters

***

## Merchant Product IDs

Map your ElasticFunnels products to merchant platform product IDs:

```json theme={null}
{
  "merchant_product_ids": {
    "buygoods": "1234",
    "clickbank": "PROD-001",
    "stripe": "prod_abc123"
  }
}
```

***

## Subscription Tiers

Products can have tiered subscription billing — different prices at different intervals (e.g. monthly then annually). Pass `subscription_tiers` as an array in the Create or Update body.

<ParamField type="boolean">
  Mark product as a subscription product
</ParamField>

<ParamField type="number">
  Default billing interval count (e.g. `1` for every-1-month)
</ParamField>

<ParamField type="string">
  `day`, `week`, `month`, or `year`
</ParamField>

<ParamField type="number">
  Free trial length in days (min: 0)
</ParamField>

<ParamField type="boolean">
  Waive the first billing charge
</ParamField>

<ParamField type="array">
  Array of tier objects. When provided, overrides the flat `subscription_frequency` / `subscription_frequency_unit` values.
</ParamField>

<ParamField type="string">
  `day`, `week`, `month`, or `year`
</ParamField>

<ParamField type="number">
  How many units of `interval` between charges (min: 1)
</ParamField>

<ParamField type="number">
  Billing amount for this tier (min: 0)
</ParamField>

<ParamField type="string">
  Optional tier label (max 64 chars)
</ParamField>

<ParamField type="string">
  Display label shown to the customer (max 255 chars)
</ParamField>

<ParamField type="number">
  Discount shown as "subscribe & save" (0–100%)
</ParamField>

```json Subscription tiers example theme={null}
{
  "is_subscription": true,
  "subscription_trial_days": 14,
  "subscribe_save_discount_percent": 15,
  "subscription_tiers": [
    {
      "tier": "monthly",
      "interval": "month",
      "interval_count": 1,
      "price": 29.99,
      "label": "Monthly — $29.99/mo"
    },
    {
      "tier": "annual",
      "interval": "year",
      "interval_count": 1,
      "price": 249.00,
      "label": "Annual — $249/yr (save 30%)"
    }
  ]
}
```

***

## Product Variants & Options

Products can have variants (e.g. size/colour combinations). Variants are managed inline via the `product_fields` and `variants` arrays on Create/Update.

### Product Fields (variant dimensions)

`product_fields` defines the variant dimensions (e.g. "Size", "Colour"):

```json theme={null}
{
  "product_fields": [
    { "name": "Size",   "type": "select", "options": ["S", "M", "L", "XL"], "position": 0 },
    { "name": "Colour", "type": "select", "options": ["Red", "Blue"],        "position": 1 }
  ]
}
```

### Variants

Each variant is a combination of field values with an optional per-variant price and SKU:

```json theme={null}
{
  "variants": [
    { "option1": "S",  "option2": "Red",  "code": "SKU-S-RED",  "price": 29.99 },
    { "option1": "M",  "option2": "Red",  "code": "SKU-M-RED",  "price": 29.99 },
    { "option1": "L",  "option2": "Blue", "code": "SKU-L-BLUE", "price": 34.99 }
  ]
}
```

<ParamField type="number">
  Existing variant ID for update (omit to create new)
</ParamField>

<ParamField type="string">
  Variant SKU/code (max 128 chars)
</ParamField>

<ParamField type="string">
  Value for the first product field (max 128 chars)
</ParamField>

<ParamField type="string">
  Value for the second product field (max 128 chars)
</ParamField>

<ParamField type="string">
  Value for the third product field (max 128 chars)
</ParamField>

<ParamField type="number">
  Override price for this variant (null = use product base price)
</ParamField>

<ParamField type="string">
  Variant image URL (max 512 chars)
</ParamField>

<ParamField type="string">
  3-letter ISO currency code (e.g. `USD`)
</ParamField>

***

## Variant Options

Variant options are brand-level reusable option sets (e.g. "Shoe Sizes", "Colours"). They can be attached to multiple products.

### List Variant Options

```
GET /api/brands/{brand}/variant-options
```

### Get All Variant Options (unpaginated)

```
GET /api/brands/{brand}/variant-options/all
```

### Create Variant Option

```
POST /api/brands/{brand}/variant-options
```

<ParamField type="string">
  Option set name (e.g. `Shirt Sizes`)
</ParamField>

<ParamField type="array">
  Array of option value strings (e.g. `["XS", "S", "M", "L", "XL"]`)
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/variant-options \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Shirt Sizes", "values": ["XS", "S", "M", "L", "XL"]}'
```

### Update Variant Option

```
PUT /api/brands/{brand}/variant-options/{variant_option}
```

### Delete Variant Option

```
DELETE /api/brands/{brand}/variant-options/{variant_option}
```

***

## Product Categories

Organise products into a two-level category hierarchy (category → subcategory).

### List Categories

```
GET /api/brands/{brand}/product-categories
```

### Get All Categories (unpaginated)

```
GET /api/brands/{brand}/product-categories/all
```

### Create Category

```
POST /api/brands/{brand}/product-categories
```

<ParamField type="string">
  Category name
</ParamField>

<ParamField type="number">
  Parent category ID — omit for top-level categories, provide for subcategories.
</ParamField>

```bash cURL — create top-level category theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/product-categories \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Supplements"}'
```

```bash cURL — create subcategory theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/product-categories \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Weight Loss", "parent_id": 3}'
```

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": 4,
    "name": "Weight Loss",
    "parent_id": 3,
    "brand_id": 42,
    "created_at": "2024-12-11T10:00:00.000000Z"
  }
  ```
</ResponseExample>

### Update Category

```
PUT /api/brands/{brand}/product-categories/{product_category}
```

### Delete Category

```
DELETE /api/brands/{brand}/product-categories/{product_category}
```

<Warning>
  When creating a product, `product_category_id` must be a **top-level** category (no `parent_id`). To assign a subcategory, also provide `product_subcategory_id` (which must belong to the category). Providing a subcategory without a category returns a 422.
</Warning>

***

## Coupons

Create and manage discount codes for products.

### List Coupons

```
GET /api/brands/{brand}/coupons
```

<ParamField type="number">
  Results per page (max 100, default: 25)
</ParamField>

### Get Coupon

```
GET /api/brands/{brand}/coupons/{coupon}
```

### Create Coupon

```
POST /api/brands/{brand}/coupons
```

<ParamField type="string">
  Coupon code (max 64 chars). Must be unique per brand.
</ParamField>

<ParamField type="string">
  `percent` — percentage off, or `fixed` — fixed amount off
</ParamField>

<ParamField type="number">
  Discount value. For `percent`, clamped to 0–100 automatically.
</ParamField>

<ParamField type="string">
  Internal label (max 128 chars)
</ParamField>

<ParamField type="string">
  `active` (default), `draft`, or `disabled`
</ParamField>

<ParamField type="array">
  Limit discount to specific product IDs. Empty/null means all products.
</ParamField>

<ParamField type="array">
  Product IDs to exclude from the discount.
</ParamField>

<ParamField type="boolean">
  Whether the coupon applies to order bump products.
</ParamField>

<ParamField type="string">
  ISO 8601 date — coupon becomes active from this date.
</ParamField>

<ParamField type="string">
  ISO 8601 date — coupon expires after this date. Must be on or after `valid_from`.
</ParamField>

<ParamField type="number">
  Maximum number of redemptions (null = unlimited).
</ParamField>

```bash cURL — 20% off all products theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/coupons \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SAVE20",
    "name": "20% Off Launch Promo",
    "type": "percent",
    "value": 20,
    "status": "active",
    "valid_from": "2024-12-01",
    "valid_until": "2024-12-31",
    "usage_limit": 500
  }'
```

```bash cURL — $10 off specific products theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/coupons \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "BOTTLE10",
    "type": "fixed",
    "value": 10,
    "product_ids": [5, 6]
  }'
```

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": 12,
    "code": "SAVE20",
    "name": "20% Off Launch Promo",
    "type": "percent",
    "value": 20,
    "status": "active",
    "product_ids": null,
    "excluded_product_ids": null,
    "applies_on_bump": false,
    "valid_from": "2024-12-01",
    "valid_until": "2024-12-31",
    "usage_limit": 500,
    "brand_id": 42,
    "created_at": "2024-12-11T10:00:00.000000Z"
  }
  ```

  ```json 422 Duplicate code theme={null}
  {
    "errors": {
      "code": ["The code has already been taken."]
    }
  }
  ```
</ResponseExample>

### Update Coupon

```
PUT /api/brands/{brand}/coupons/{coupon}
```

All fields optional on update. Use this to disable an expired coupon:

```bash cURL — disable coupon theme={null}
curl -X PUT https://app.elasticfunnels.io/api/brands/{brand_id}/coupons/12 \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"status": "disabled"}'
```

### Delete Coupon

```
DELETE /api/brands/{brand}/coupons/{coupon}
```

### Validate Coupon

Check if a coupon code is valid and get its details (useful for frontend validation before applying at checkout).

```
GET /api/brands/{brand}/coupons/validate?code=SAVE20
```

<ParamField type="string">
  Coupon code to validate
</ParamField>

<ResponseExample>
  ```json 200 Valid theme={null}
  {
    "valid": true,
    "coupon": {
      "id": 12,
      "code": "SAVE20",
      "type": "percent",
      "value": 20,
      "product_ids": null
    }
  }
  ```

  ```json 200 Invalid theme={null}
  {
    "valid": false,
    "reason": "Coupon has expired."
  }
  ```
</ResponseExample>

***

## Notes

<Info>
  * Product `code` must be unique within the brand
  * `classification` of `bonus` products are automatically included with their parent products
  * Subscription products require `subscription_frequency` and `subscription_frequency_unit`
  * All costs (COGS, fulfillment, packaging) are tracked for profit margin calculations
  * Images are returned as both `image` (relative path) and `image_link` (full URL)
  * Downloadable assets live in `product_files`, not top-level `bonus_file` / `digital_file` columns
    * `product_category_id` must be a root-level category; use `product_subcategory_id` for sub-level
    * Coupon `type: "percent"` values are clamped to 0–100 automatically
</Info>

<Warning>
  When updating products that are actively used in funnels, changes may affect existing customer orders and analytics.
</Warning>


# Quizzes
Source: https://docs.elasticfunnels.io/api-reference/endpoints/quizzes

Create and manage quizzes, screens, and flow data

<Note>
  Quiz endpoints sit under `/api/brands/{brand}/quizzes/` with `moduleAccess:quizzes` middleware. Authenticate with `EF-Access-Key`.
</Note>

***

## List Quizzes

```
GET /api/brands/{brand}/quizzes
```

<ParamField type="number">
  Results per page (1–100, default: 25)
</ParamField>

<ParamField type="string">
  Search by name
</ParamField>

<ParamField type="string">
  `newest`, `oldest`, `created_at`, `updated_at`
</ParamField>

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/quizzes \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "current_page": 1,
    "data": [
      {
        "id": 4,
        "code": "health-quiz-xyz",
        "name": "Health Assessment Quiz",
        "page_id": 201,
        "total_entries": 312,
        "updated_at": "2024-12-10T15:00:00.000000Z"
      }
    ],
    "per_page": 25,
    "total": 4,
    "last_page": 1
  }
  ```
</ResponseExample>

***

## List Quizzes (Unpaginated)

```
GET /api/brands/{brand}/quizzes/all
```

Returns `{ id, name, code }` for all quizzes — useful for dropdowns and mapping.

***

## Get Quiz

```
GET /api/brands/{brand}/quizzes/{quiz}
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 4,
    "code": "health-quiz-xyz",
    "name": "Health Assessment Quiz",
    "page_id": 201,
    "page": { "id": 201, "title": "Health Quiz Page", "slug": "health-quiz" },
    "total_entries": 312,
    "config": { /* quiz theme/layout config */ },
    "fields": [
      { "id": 10, "code": "screen-abc", "name": "Question 1", "type": "single_choice", "order": 0 }
    ],
    "slug": "health-quiz",
    "domain": { "domain": "quiz.mybrand.com" }
  }
  ```
</ResponseExample>

<Note>
  `flow_data` is **not** included in the `show` response. Use `GET .../flow` to retrieve the flow graph.
</Note>

***

## Create Quiz

```
POST /api/brands/{brand}/quizzes
```

<ParamField type="string">
  Quiz name
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/quizzes \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Health Assessment Quiz"}'
```

<ResponseExample>
  ```json 200 Created theme={null}
  {
    "quiz": {
      "id": 4,
      "code": "health-quiz-xyz",
      "name": "Health Assessment Quiz",
      "page_id": 201,
      "total_entries": 0
    }
  }
  ```

  ```json 403 Plan limit theme={null}
  {
    "error": "Plan limit exceeded",
    "plan_error": {
      "type": "plan_upgrade_required",
      "feature": "quizzes",
      "message": "Your plan does not allow creating more quizzes.",
      "plan_name": "Starter",
      "upgrade_info": {}
    },
    "errors": { /* field errors */ }
  }
  ```
</ResponseExample>

***

## Update Quiz

```
PUT /api/brands/{brand}/quizzes/{quiz}
```

<ParamField type="string">
  Quiz name (max 255)
</ParamField>

<ParamField type="number">
  ID of the page to associate with this quiz
</ParamField>

<ParamField type="object">
  Quiz display configuration (theme, layout, computed variables, etc.)
</ParamField>

<ResponseExample>
  ```json 200 Updated theme={null}
  {
    "id": 4,
    "code": "health-quiz-xyz",
    "name": "Health Assessment Quiz",
    "config": { /* updated config */ }
  }
  ```

  ```json 422 Validation error theme={null}
  {
    "message": "Validation failed.",
    "errors": {
      "name": ["The name field is required."]
    },
    "component_errors": []
  }
  ```
</ResponseExample>

***

## Delete Quiz

```
DELETE /api/brands/{brand}/quizzes/{quiz}
```

<ResponseExample>
  ```json Response theme={null}
  { "success": true }
  ```
</ResponseExample>

***

## Get Quiz Flow

Returns the visual flow graph (Drawflow format) and all screen definitions.

```
GET /api/brands/{brand}/quizzes/{quiz}/flow
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/quizzes/4/flow \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "flow": {
      "drawflow": {
        "Home": {
          "data": {
            "1": { "id": 1, "name": "Question 1", "inputs": {}, "outputs": {} },
            "2": { "id": 2, "name": "Result Screen", "inputs": {}, "outputs": {} }
          }
        }
      }
    },
    "screens": [
      {
        "id": 10,
        "code": "screen-abc",
        "name": "Question 1",
        "type": "single_choice",
        "order": 0
      }
    ]
  }
  ```
</ResponseExample>

<Info>
  If no flow has been saved yet, `flow` defaults to a minimal empty Drawflow structure (`{"drawflow":{"Home":{"data":[]}}}`).
</Info>

***

## Save Quiz Flow

```
POST /api/brands/{brand}/quizzes/{quiz}/flow
```

<ParamField type="any">
  The complete Drawflow graph object. Can be `null` to clear the flow.
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/quizzes/4/flow \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"flow": { /* drawflow object */ }}'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "message": "Flow saved successfully"
  }
  ```
</ResponseExample>

***

## Screens

Quiz screens are the individual question/result pages within a quiz. They are nested under the quiz resource.

### List Screens

```
GET /api/brands/{brand}/quizzes/{quiz}/screens
```

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": 10,
        "code": "screen-abc",
        "name": "Do you experience bloating?",
        "type": "single_choice",
        "order": 0,
        "options": [
          { "label": "Yes, often", "value": "often" },
          { "label": "Sometimes", "value": "sometimes" },
          { "label": "Never", "value": "never" }
        ],
        "style": "light"
      }
    ]
  }
  ```
</ResponseExample>

### Get Screen

```
GET /api/brands/{brand}/quizzes/{quiz}/screens/{screen}
```

### Create Screen

```
POST /api/brands/{brand}/quizzes/{quiz}/screens
```

<ParamField type="string">
  Screen name / question title
</ParamField>

<ParamField type="string">
  Screen type: `single_choice`, `multiple_choice`, `text_input`, `rating`, `result`, `info`, `video`, `image`
</ParamField>

<ParamField type="string">
  Display title shown to the user
</ParamField>

<ParamField type="string">
  Subtitle or question description
</ParamField>

<ParamField type="array">
  Answer options (for choice screens) — each with `label` and `value`
</ParamField>

<ParamField type="object">
  Additional screen-level configuration
</ParamField>

<ParamField type="string">
  HTML content (for `info` and `result` screens)
</ParamField>

<ParamField type="string">
  `light` or `dark`
</ParamField>

<ParamField type="number">
  Display order. Auto-incremented if omitted.
</ParamField>

<ParamField type="file">
  Audio file upload (multipart)
</ParamField>

<ParamField type="file">
  Image file upload (multipart)
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/quizzes/4/screens \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bloating Question",
    "type": "single_choice",
    "title": "Do you experience bloating after meals?",
    "style": "light",
    "options": [
      {"label": "Yes, often", "value": "often"},
      {"label": "Sometimes", "value": "sometimes"},
      {"label": "Never", "value": "never"}
    ]
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "quiz": {
      "id": 10,
      "code": "screen-abc",
      "name": "Bloating Question",
      "type": "single_choice",
      "order": 3
    }
  }
  ```

  <Note>
    The response key is `"quiz"` even though the value is a screen object. This is a known naming quirk.
  </Note>
</ResponseExample>

### Update Screen

```
PUT /api/brands/{brand}/quizzes/{quiz}/screens/{screen}
```

Same body as Create.

### Delete Screen

```
DELETE /api/brands/{brand}/quizzes/{quiz}/screens/{screen}
```

<ResponseExample>
  ```json Response theme={null}
  { "success": true }
  ```
</ResponseExample>

### Reorder Screens

```
POST /api/brands/{brand}/quizzes/{quiz}/screens/order
```

<ParamField type="object">
  Map of `{ "<screenId>": <integer order>, ... }`
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/quizzes/4/screens/order \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"order": {"10": 0, "11": 1, "12": 2}}'
```

<ResponseExample>
  ```json Response theme={null}
  { "success": true }
  ```
</ResponseExample>

### Duplicate Screen

```
POST /api/brands/{brand}/quizzes/{quiz}/screens/{screen}/duplicate
```

Creates an exact copy of the screen with a new code and auto-assigned order.

<ResponseExample>
  ```json Response theme={null}
  { "success": true }
  ```
</ResponseExample>

***

## Notes

<Info>
  * `flow_data` is separate from the quiz's `config` and screen definitions — save and retrieve it with the dedicated `/flow` endpoints
  * Screen `code` values are auto-generated unique identifiers used in the flow graph to connect questions to answer paths
  * `total_entries` tracks submission count and is incremented automatically when entries are submitted via the public form
</Info>


# Split Tests
Source: https://docs.elasticfunnels.io/api-reference/endpoints/split-tests

Create and manage A/B split tests, read statistical results, declare winners

<Note>
  All split test endpoints authenticate via `EF-Access-Key` with `brandAccess` middleware. Request bodies are nested under a `split_test` key.
</Note>

***

## List Split Tests

```
GET /api/brands/{brand}/split-tests
```

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="number">
  Results per page (1–100, default: 25)
</ParamField>

<ParamField type="string">
  Filter by status: `running`, `paused`, `finalized`, `deleted`
</ParamField>

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/split-tests?status=running" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "current_page": 1,
    "data": [
      {
        "id": 7,
        "name": "Headline Test — Hero Section",
        "type": "split_test",
        "status": "running",
        "page_id": 101,
        "funnel_id": null,
        "start_date": "2024-12-01",
        "end_date": "2024-12-31",
        "duration": 30,
        "auto_select_winner": false,
        "winner_selection_criteria": null,
        "winner_selection_confidence": 95,
        "sample_size_limit": null,
        "baseline": "control",
        "views": 4820,
        "time_left": "20 days",
        "user": { "id": 1, "name": "Sam" },
        "page": { "id": 101, "title": "Nutra Landing Page" },
        "funnel": null,
        "created_at": "2024-12-01T10:00:00.000000Z"
      }
    ],
    "per_page": 25,
    "total": 3,
    "last_page": 1
  }
  ```
</ResponseExample>

***

## Get Split Test

```
GET /api/brands/{brand}/split-tests/{split_test}
```

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Split test ID
</ParamField>

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/split-tests/7 \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 7,
    "name": "Headline Test — Hero Section",
    "type": "split_test",
    "status": "running",
    "page_id": 101,
    "funnel_id": null,
    "start_date": "2024-12-01",
    "end_date": "2024-12-31",
    "statistical_method": "frequentist",
    "significance_level": 0.05,
    "statistical_power": 0.8,
    "primary_metric": "conversion_rate",
    "config": {
      "items": [
        { "name": "Control", "node_code": "ctrl-abc123", "weight": 50 },
        { "name": "Variant B", "node_code": "var-def456", "weight": 50 }
      ]
    },
    "winner": null,
    "goals": [
      { "name": "Purchase", "value": "purchase" }
    ],
    "created_at": "2024-12-01T10:00:00.000000Z",
    "updated_at": "2024-12-10T15:30:00.000000Z"
  }
  ```
</ResponseExample>

***

## Create Split Test

```
POST /api/brands/{brand}/split-tests
```

<Note>
  All body fields must be nested under the `split_test` key (e.g. `split_test.name`, `split_test.config`).
</Note>

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Human-readable name for the test
</ParamField>

<ParamField type="string">
  `split_test` (funnel/page variants) or `component_split_test` (component-level test)
</ParamField>

<ParamField type="object">
  Test configuration including `items` array. Each item has `name`, `node_code`, and `weight`.
</ParamField>

<ParamField type="string">
  `running`, `paused`, `completed`, `deleted` (default: `running`)
</ParamField>

<ParamField type="string">
  ISO 8601 date (default: today)
</ParamField>

<ParamField type="string">
  ISO 8601 date
</ParamField>

<ParamField type="string">
  Primary metric to optimise for (e.g. `conversion_rate`, `revenue`)
</ParamField>

<ParamField type="string">
  `frequentist` (default) or `bayesian`
</ParamField>

<ParamField type="number">
  Alpha level (0.001–0.5, default: 0.05)
</ParamField>

<ParamField type="number">
  Beta level (0.1–0.99, default: 0.8)
</ParamField>

<ParamField type="number">
  Minimum visitors per variant before declaring a winner (100–1,000,000)
</ParamField>

<ParamField type="boolean">
  Automatically select winner when confidence threshold is reached
</ParamField>

<ParamField type="number">
  Confidence % required for auto-winner selection (e.g. `95`)
</ParamField>

<ParamField type="array">
  Conversion goal events. Each goal has `name` (string) and `value` (alphanumeric slug).
</ParamField>

<ParamField type="string">
  The control variant's name or node code
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/split-tests \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "split_test": {
      "name": "Headline Test — Hero Section",
      "type": "split_test",
      "status": "running",
      "page_id": 101,
      "primary_metric": "conversion_rate",
      "significance_level": 0.05,
      "winner_selection_confidence": 95,
      "start_date": "2024-12-01",
      "end_date": "2024-12-31",
      "goals": [
        { "name": "Purchase", "value": "purchase" }
      ],
      "config": {
        "items": [
          { "name": "Control",   "node_code": "ctrl-abc123", "weight": 50 },
          { "name": "Variant B", "node_code": "var-def456",  "weight": 50 }
        ]
      }
    }
  }'
```

<ResponseExample>
  ```json 200 Created theme={null}
  {
    "id": 7,
    "name": "Headline Test — Hero Section",
    "type": "split_test",
    "status": "running",
    "page_id": 101,
    "brand_id": 42,
    "start_date": "2024-12-01",
    "end_date": "2024-12-31",
    "primary_metric": "conversion_rate",
    "significance_level": 0.05,
    "statistical_method": "frequentist",
    "winner_selection_confidence": 95,
    "config": {
      "items": [
        { "name": "Control",   "node_code": "ctrl-abc123", "weight": 50 },
        { "name": "Variant B", "node_code": "var-def456",  "weight": 50 }
      ]
    },
    "goals": [{ "name": "Purchase", "value": "purchase" }],
    "created_at": "2024-12-01T10:00:00.000000Z"
  }
  ```

  ```json 422 Validation error theme={null}
  {
    "errors": {
      "split_test.name": ["The split test.name field is required."],
      "split_test.config": ["The split test.config field is required."]
    }
  }
  ```
</ResponseExample>

***

## Update Split Test

```
PUT /api/brands/{brand}/split-tests/{split_test}
```

Same body structure as Create — all fields nested under `split_test`, all optional on update except as noted. To pause a running test: set `split_test.status` to `paused`.

```bash cURL — pause a running test theme={null}
curl -X PUT https://app.elasticfunnels.io/api/brands/{brand_id}/split-tests/7 \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"split_test": {"status": "paused"}}'
```

```bash cURL — extend end date theme={null}
curl -X PUT https://app.elasticfunnels.io/api/brands/{brand_id}/split-tests/7 \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"split_test": {"end_date": "2025-01-15"}}'
```

<ResponseExample>
  ```json 200 Updated theme={null}
  {
    "id": 7,
    "name": "Headline Test — Hero Section",
    "status": "paused",
    "end_date": "2025-01-15",
    "updated_at": "2024-12-11T09:00:00.000000Z"
  }
  ```
</ResponseExample>

***

## Delete Split Test

```
DELETE /api/brands/{brand}/split-tests/{split_test}
```

```bash cURL theme={null}
curl -X DELETE https://app.elasticfunnels.io/api/brands/{brand_id}/split-tests/7 \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json 200 theme={null}
  {
    "message": "Split test deleted successfully."
  }
  ```
</ResponseExample>

***

## Get Chart Data

Retrieve time-series and comparison data for visualisations.

```
GET /api/brands/{brand}/split-tests/{split_test}/chart-data
```

<ParamField type="string">
  Split test ID
</ParamField>

<ParamField type="string">
  One of: `conversion_trends`, `funnel_analysis`, `statistical_confidence`, `performance_comparison`
</ParamField>

<ParamField type="string">
  Start date (ISO 8601)
</ParamField>

<ParamField type="string">
  End date (ISO 8601)
</ParamField>

<ParamField type="string">
  Timezone (e.g. `America/New_York`)
</ParamField>

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/split-tests/7/chart-data?chart_type=conversion_trends&start=2024-12-01&end=2024-12-10" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json conversion_trends theme={null}
  {
    "chart_type": "conversion_trends",
    "labels": ["Dec 1", "Dec 2", "Dec 3"],
    "datasets": [
      {
        "label": "Control",
        "data": [0.031, 0.033, 0.029],
        "node_code": "ctrl-abc123"
      },
      {
        "label": "Variant B",
        "data": [0.038, 0.041, 0.039],
        "node_code": "var-def456"
      }
    ]
  }
  ```

  ```json statistical_confidence theme={null}
  {
    "chart_type": "statistical_confidence",
    "variants": [
      {
        "name": "Control",
        "node_code": "ctrl-abc123",
        "conversion_rate": 0.031,
        "conversions": 149,
        "visitors": 4806,
        "confidence": null,
        "is_baseline": true
      },
      {
        "name": "Variant B",
        "node_code": "var-def456",
        "conversion_rate": 0.039,
        "conversions": 188,
        "visitors": 4820,
        "confidence": 87.4,
        "lift": 25.8,
        "is_winner": false
      }
    ],
    "required_confidence": 95,
    "has_winner": false
  }
  ```
</ResponseExample>

***

## Declare Winner

Manually select the winning variant and finalize the test. Sets `status` to `finalized`.

```
POST /api/brands/{brand}/split-tests/{split_test}/declare-winner
```

<ParamField type="string">
  The `node_code` of the winning variant
</ParamField>

<ParamField type="string">
  Display name of the winning variant
</ParamField>

<ParamField type="number">
  Statistical confidence at time of declaration (0–100)
</ParamField>

<ParamField type="number">
  Relative lift over baseline (e.g. `25.8` for 25.8% improvement)
</ParamField>

<ParamField type="string">
  Free-text note for the decision (max 500 chars)
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/split-tests/7/declare-winner \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "winner_node_code": "var-def456",
    "variant_name": "Variant B",
    "confidence": 87.4,
    "improvement": 25.8,
    "reason": "Strong uplift on mobile; acceptable confidence given campaign deadline."
  }'
```

<ResponseExample>
  ```json 200 Winner declared theme={null}
  {
    "message": "Winner declared successfully",
    "split_test": {
      "id": 7,
      "status": "finalized",
      "winner_selected_at": "2024-12-11T09:15:00.000000Z",
      "winner_selected_by": "manual"
    },
    "winner": {
      "variant": "Variant B",
      "node_code": "var-def456",
      "confidence": 87.4,
      "improvement": 25.8
    }
  }
  ```
</ResponseExample>

***

## Export Results

Queue a CSV/Excel export of all split test results. An email is sent when ready.

```
POST /api/brands/{brand}/split-tests/{split_test}/export
```

<ParamField type="string">
  `csv` (default) or `excel`
</ParamField>

<ParamField type="boolean">
  Include p-values, confidence intervals, lift (default: `true`)
</ParamField>

<ParamField type="boolean">
  Include CI columns (default: `false`)
</ParamField>

<ParamField type="object">
  Optional `{start, end}` to restrict export date range
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/split-tests/7/export \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"format": "csv", "include_statistics": true}'
```

<ResponseExample>
  ```json 200 theme={null}
  {
    "message": "Export has been queued. You will receive an email when it's ready.",
    "status": "queued",
    "split_test_name": "Headline Test — Hero Section"
  }
  ```
</ResponseExample>

***

## Get Node Codes

Return the variant names and `node_code` identifiers for a split test — useful for linking analytics filter calls.

```
GET /api/brands/{brand}/split-tests/{split_test}/node-codes
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/split-tests/7/node-codes \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  [
    { "code": "ctrl-abc123", "name": "Control" },
    { "code": "var-def456",  "name": "Variant B" }
  ]
  ```
</ResponseExample>

***

## Quick Access Stats

Counts by status — useful for dashboard badges.

```
GET /api/brands/{brand}/split-tests/quick-access
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/split-tests/quick-access \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "all": 12,
    "running": 3,
    "finalized": 7,
    "not_running": 2
  }
  ```
</ResponseExample>

***

## Notes

Add freeform notes to a split test for team collaboration.

### List notes

```
GET /api/brands/{brand}/split-tests/{split_test}/notes
```

### Add note

```
POST /api/brands/{brand}/split-tests/{split_test}/notes
```

<ParamField type="string">
  Note text
</ParamField>

### Delete note

```
DELETE /api/brands/{brand}/split-tests/{split_test}/notes/{note}
```

```bash cURL — add note theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/split-tests/7/notes \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"content": "Pausing — holiday traffic skewing mobile numbers."}'
```

<ResponseExample>
  ```json Note added theme={null}
  {
    "id": 3,
    "split_test_id": 7,
    "content": "Pausing — holiday traffic skewing mobile numbers.",
    "user": { "id": 1, "name": "Sam" },
    "created_at": "2024-12-11T09:30:00.000000Z"
  }
  ```
</ResponseExample>

***

## Using Split Test Data with Analytics

To filter analytics metrics by split test variant, pass the `split_test_id` and `filter[node_code]` to the analytics endpoints:

```bash theme={null}
# Metrics for a specific variant
GET /api/brands/{brand}/analytics/metrics/data
  ?start=2024-12-01T00:00:00Z
  &end=2024-12-10T23:59:59Z
  &selected_metrics[]=conversion_rate&selected_metrics[]=revenue
  &split_test_id=7
  &filter[node_code]=var-def456
```

```bash theme={null}
# Compare metrics across all variants grouped by node_code
GET /api/brands/{brand}/analytics/metrics/node_code/data
  ?start=2024-12-01T00:00:00Z
  &end=2024-12-10T23:59:59Z
  &selected_metrics[]=conversion_rate
  &split_test_id=7
```


# Subscriptions
Source: https://docs.elasticfunnels.io/api-reference/endpoints/subscriptions

Manage subscription lifecycle, analytics, and retention

## List Subscriptions

Returns a paginated list of subscriptions for the brand. Supports filters for status, date ranges, search, merchant, and product.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="number">
  Page number for pagination
</ParamField>

<ParamField type="number">
  Results per page
</ParamField>

<ParamField type="string">
  Filter by subscription status: `active`, `trial`, `paused`, `past_due`, `canceled` (use `all` or omit for no status filter)
</ParamField>

<ParamField type="string">
  Search by customer name, email, public order ID, or transaction ID
</ParamField>

<ParamField type="string">
  Start of date range (ISO 8601 or date string accepted by the API)
</ParamField>

<ParamField type="string">
  End of date range (ISO 8601 or date string accepted by the API)
</ParamField>

<ParamField type="number">
  Filter by merchant ID
</ParamField>

<ParamField type="string">
  Filter by product code
</ParamField>

<ParamField type="string">
  Filter by customer email
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/subscriptions
```

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/subscriptions?status=active&page=1" \
  -H "EF-Access-Key: your_api_key_here"
```

***

## Show Subscription

Returns full details of a single subscription (identified by **transaction ID**), including enriched subscription flags from the conversion record.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Subscription **transaction ID** (not the public order code)
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/subscriptions/{id}
```

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/subscriptions/{transaction_id}" \
  -H "EF-Access-Key: your_api_key_here"
```

***

## Update Subscription Flag

Updates a keyed flag on the subscription conversion (for example `subscription_status`, `subscription_next_charge_at`). In practice, prefer the **dedicated POST endpoints** below for lifecycle actions; they perform validation and side effects. Use a generic flag update only when you need to align data with an external system and your deployment exposes this route.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Subscription transaction ID
</ParamField>

<ParamField type="string">
  Flag key (e.g. `subscription_status`, `subscription_next_charge_at`)
</ParamField>

<ParamField type="string">
  New value for the flag
</ParamField>

```bash Request theme={null}
PATCH /api/brands/{brand}/subscriptions/{id}/flag
```

```bash cURL theme={null}
curl -X PATCH "https://app.elasticfunnels.io/api/brands/{brand_id}/subscriptions/{transaction_id}/flag" \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"key":"subscription_status","value":"paused"}'
```

<Note>
  If this path returns 404, use **Pause**, **Resume**, **Reactivate**, **Change Next Bill Date**, and related POST routes in this reference instead.
</Note>

***

## Skip Next Charge

Advances the subscription by one billing cycle without taking payment now (skips the next scheduled charge).

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Subscription transaction ID
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/subscriptions/{id}/skip
```

```bash cURL theme={null}
curl -X POST "https://app.elasticfunnels.io/api/brands/{brand_id}/subscriptions/{transaction_id}/skip" \
  -H "EF-Access-Key: your_api_key_here"
```

***

## Force Bill

Triggers an immediate billing attempt for the subscription.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Subscription transaction ID
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/subscriptions/{id}/force-bill
```

```bash cURL theme={null}
curl -X POST "https://app.elasticfunnels.io/api/brands/{brand_id}/subscriptions/{transaction_id}/force-bill" \
  -H "EF-Access-Key: your_api_key_here"
```

***

## Change Next Charge Date

Updates the next billing date for the subscription.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Subscription transaction ID
</ParamField>

<ParamField type="string">
  New charge date/time (must be after now; ISO 8601 recommended)
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/subscriptions/{id}/change-next-bill-date
```

```bash cURL theme={null}
curl -X POST "https://app.elasticfunnels.io/api/brands/{brand_id}/subscriptions/{transaction_id}/change-next-bill-date" \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"next_charge_at":"2026-04-15T12:00:00Z"}'
```

***

## Reactivate Subscription

Reactivates a canceled (or otherwise eligible) subscription.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Subscription transaction ID
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/subscriptions/{id}/reactivate
```

```bash cURL theme={null}
curl -X POST "https://app.elasticfunnels.io/api/brands/{brand_id}/subscriptions/{transaction_id}/reactivate" \
  -H "EF-Access-Key: your_api_key_here"
```

***

## Subscription Emails

Returns the email log for a subscription (from brand email logs when available).

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Subscription transaction ID
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/subscriptions/{id}/emails
```

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/subscriptions/{transaction_id}/emails" \
  -H "EF-Access-Key: your_api_key_here"
```

***

## Analytics Endpoints

### Summary

Returns key metrics such as active count, MRR, churn, and average LTV (exact fields depend on implementation).

```bash Request theme={null}
GET /api/brands/{brand}/subscriptions/analytics/summary
```

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/subscriptions/analytics/summary" \
  -H "EF-Access-Key: your_api_key_here"
```

### MRR Trend

Returns monthly MRR values over time.

```bash Request theme={null}
GET /api/brands/{brand}/subscriptions/analytics/mrr-trend
```

### Churn Trend

Returns monthly churn rate values over time.

```bash Request theme={null}
GET /api/brands/{brand}/subscriptions/analytics/churn-trend
```

### Cohort LTV

Returns lifetime value analysis grouped by subscription start month.

```bash Request theme={null}
GET /api/brands/{brand}/subscriptions/analytics/cohort-ltv
```

### Dunning Stats

Returns dunning recovery metrics: totals in dunning, recovered, lost, and recovery rate.

```bash Request theme={null}
GET /api/brands/{brand}/subscriptions/analytics/dunning-stats
```

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/subscriptions/analytics/dunning-stats" \
  -H "EF-Access-Key: your_api_key_here"
```

***

## Retention Offers

Retention configuration is stored **per merchant**. Replace `{merchant}` with the merchant record ID.

### Get Retention Offers

Returns the merchant's configured retention offers and exit survey reasons.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Merchant ID
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/merchants/{merchant}/retention-offers
```

### Save Retention Offers

Updates the merchant's retention offer configuration.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  Merchant ID
</ParamField>

<ParamField type="object">
  Configuration object: `enabled`, `offers` (array with `offer_type`, optional `cancel_reason`, `offer_value`, `offer_label`, `offer_duration_cycles`, `offer_product_code`), and optional `exit_survey_reasons`
</ParamField>

```bash Request theme={null}
PUT /api/brands/{brand}/merchants/{merchant}/retention-offers
```

```bash cURL theme={null}
curl -X PUT "https://app.elasticfunnels.io/api/brands/{brand_id}/merchants/{merchant_id}/retention-offers" \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"retention_offers":{"enabled":true,"offers":[],"exit_survey_reasons":[]}}'
```

### Apply Retention Offer

Applies a retention offer to a specific subscription transaction.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The subscription transaction ID
</ParamField>

<ParamField type="integer">
  Merchant ID that owns the transaction
</ParamField>

<ParamField type="string">
  `discount`, `pause`, or `downgrade`
</ParamField>

<ParamField type="number">
  For `discount`, percent off; for `pause`, pause length in **days** (minimum 1)
</ParamField>

<ParamField type="integer">
  For `discount`, number of billing cycles the discount applies
</ParamField>

<ParamField type="string">
  For `downgrade`, target product code when applicable
</ParamField>

<ParamField type="string">
  Customer's selected cancellation reason
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/retention-offers/apply
```

```bash cURL theme={null}
curl -X POST "https://app.elasticfunnels.io/api/brands/{brand_id}/retention-offers/apply" \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"transaction_id":"...","merchant_id":1,"offer_type":"discount","offer_value":15,"offer_duration_cycles":3,"cancel_reason":"Too expensive"}'
```


# Tickets
Source: https://docs.elasticfunnels.io/api-reference/endpoints/tickets

Manage support tickets and customer inquiries

## List Tickets

Retrieve all support tickets for a project.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="number">
  Page number for pagination (default: 1)
</ParamField>

<ParamField type="number">
  Number of results per page (default: 30)
</ParamField>

<ParamField type="string">
  Filter by status: `open`, `closed`, `waiting`, `resolved`, `spam`
</ParamField>

<ParamField type="string">
  Search tickets by subject, email, or content
</ParamField>

<ParamField type="string">
  Sort order: `date_asc` or `date_desc`
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/tickets
```

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/tickets?status=open&page=1" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "brand_id": 123,
        "ticket_code": "TKT-12345",
        "type": "support",
        "status": "open",
        "subject": "Question about my order",
        "from_name": "John Doe",
        "from_email": "john@example.com",
        "customer_email": "john@example.com",
        "preview_message": "I have a question about...",
        "read": false,
        "created_at": "2024-12-10T10:30:00.000000Z",
        "updated_at": "2024-12-10T10:30:00.000000Z",
        "created_at_label": "2 hours ago",
        "status_label": "Open"
      }
    ],
    "meta": {
      "current_page": 1,
      "per_page": 30,
      "total": 45
    },
    "statuses": {
      "open": 15,
      "waiting": 10,
      "closed": 18,
      "resolved": 2,
      "spam": 0
    }
  }
  ```
</ResponseExample>

***

## Get Ticket Statuses

Get count of tickets by status.

<ParamField type="string">
  The brand/project ID
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/tickets/statuses
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/tickets/statuses \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "open": 15,
    "waiting": 10,
    "closed": 18,
    "resolved": 2,
    "spam": 0
  }
  ```
</ResponseExample>

***

## Mark Ticket as Read

Mark a ticket as read.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The ticket code (e.g., "TKT-12345")
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/tickets/{ticket_code}/mark-as-read
```

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/tickets/TKT-12345/mark-as-read \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "message": "Ticket marked as read"
  }
  ```
</ResponseExample>

***

## Mark Ticket as Unread

Mark a ticket as unread.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The ticket code (e.g., "TKT-12345")
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/tickets/{ticket_code}/mark-as-unread
```

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/tickets/TKT-12345/mark-as-unread \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "message": "Ticket marked as unread"
  }
  ```
</ResponseExample>

***

## List Ticket Messages

Get all messages in a ticket conversation.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The ticket code (e.g., "TKT-12345")
</ParamField>

```bash Request theme={null}
GET /api/brands/{brand}/tickets/{ticket_code}/messages
```

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/tickets/TKT-12345/messages \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "brand_id": 123,
        "ticket_code": "TKT-12345",
        "status": "open",
        "type": "customer_message",
        "message": "<p>I have a question about my order...</p>",
        "message_type": "text",
        "from_name": "John Doe",
        "created_at": "2024-12-10T10:30:00.000000Z",
        "created_at_label": "2 hours ago",
        "status_label": "Open"
      },
      {
        "brand_id": 123,
        "ticket_code": "TKT-12345",
        "status": "waiting",
        "type": "agent_message",
        "message": "<p>Hi John, I'd be happy to help...</p>",
        "message_type": "text",
        "from_name": "Support Agent",
        "created_at": "2024-12-10T10:45:00.000000Z",
        "created_at_label": "1 hour ago",
        "status_label": "Waiting"
      }
    ]
  }
  ```
</ResponseExample>

***

## Send Ticket Reply

Send a reply message to a ticket.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The ticket code (e.g., "TKT-12345")
</ParamField>

<ParamField type="string">
  The reply message (HTML supported)
</ParamField>

<ParamField type="string">
  Message type: `agent_message` or `system_message`
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/tickets/{ticket_code}/messages
```

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/tickets/TKT-12345/messages \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "<p>Thank you for contacting us. Your order is being processed...</p>",
    "type": "agent_message"
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "brand_id": 123,
    "ticket_code": "TKT-12345",
    "status": "waiting",
    "type": "agent_message",
    "message": "<p>Thank you for contacting us. Your order is being processed...</p>",
    "from_name": "Support Agent",
    "created_at": "2024-12-10T12:00:00.000000Z"
  }
  ```
</ResponseExample>

***

## Set Ticket Status

Update the status of a ticket.

<ParamField type="string">
  The brand/project ID
</ParamField>

<ParamField type="string">
  The ticket code (e.g., "TKT-12345")
</ParamField>

<ParamField type="string">
  New status: `open`, `waiting`, `closed`, `resolved`, `spam`
</ParamField>

```bash Request theme={null}
POST /api/brands/{brand}/tickets/{ticket_code}/set-status/{status}
```

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/tickets/TKT-12345/set-status/resolved \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "message": "Email sent"
  }
  ```
</ResponseExample>

***

## Ticket Status Values

| Status | Description |
| - | - |
| `open` | New ticket or reopened ticket |
| `waiting` | Waiting for customer response |
| `closed` | Ticket has been closed |
| `resolved` | Issue has been resolved |
| `spam` | Marked as spam |

***

## Message Types

| Type | Description |
| - | - |
| `customer_message` | Message from customer |
| `agent_message` | Message from support agent |
| `system_message` | Automated system message |

***

## Notes

<Info>
  * Tickets are automatically sorted by `created_at` for open tickets and `updated_at` for closed/resolved/spam tickets
  * Sending a reply automatically changes ticket status to "waiting"
  * The AI reply generation uses customer order history and purchase data when available
  * All ticket messages support HTML formatting
</Info>


# Tracking
Source: https://docs.elasticfunnels.io/api-reference/endpoints/tracking

Access click data, session replays, and manage short links

<Note>
  Tracking endpoints sit under `/api/brands/{brand}/` with `moduleAccess:tracking` middleware. Authenticate with `EF-Access-Key`.
</Note>

***

## Clicks

The Clicks API exposes click tracking data from visitor sessions. Clicks are stored in Elasticsearch (or ClickHouse when enabled for the account).

### List Clicks

```
GET /api/brands/{brand}/clicks
```

<Note>
  Page size is fixed at **30** for the clicks index and cannot be changed via `per_page`.
</Note>

<ParamField type="number">
  Page number (default: 1)
</ParamField>

<ParamField type="string">
  Filter by URL (partial match)
</ParamField>

<ParamField type="string">
  Filter by Sub ID 1 (`sub` tracking parameter)
</ParamField>

<ParamField type="string">
  Filter by Sub ID 2
</ParamField>

<ParamField type="string">
  Filter by Sub ID 3
</ParamField>

<ParamField type="string">
  Filter by Sub ID 4
</ParamField>

<ParamField type="string">
  Filter by visit tracking ID
</ParamField>

<ParamField type="string">
  Filter by specific click/session ID — collapses results to unique sessions
</ParamField>

<ParamField type="string">
  Filter by IP address
</ParamField>

<ParamField type="number">
  Filter by page ID
</ParamField>

<ParamField type="number">
  Filter by funnel ID
</ParamField>

<ParamField type="number">
  Filter by merchant ID
</ParamField>

<ParamField type="boolean">
  Exclude bot traffic from results
</ParamField>

<ParamField type="string">
  Date range start (ISO 8601). Used by `DateRangeService`.
</ParamField>

<ParamField type="string">
  Column to sort by (limited to sortable fields)
</ParamField>

<ParamField type="string">
  Sort direction: `asc` or `desc`
</ParamField>

```bash cURL theme={null}
curl "https://app.elasticfunnels.io/api/brands/{brand_id}/clicks?funnel_id=5&page=1" \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "total": 1240,
    "last_page": 42,
    "current_page": 1,
    "per_page": 30,
    "next_page_url": true,
    "data": [
      {
        "id": "click-es-doc-abc",
        "session_id": "sess-xyz-123",
        "ip_address": "203.0.113.50",
        "url": "/checkout",
        "funnel_id": 5,
        "domain": { "id": 7, "domain": "checkout.mybrand.com" },
        "affiliate": null,
        "merchant": { "id": 1, "merchant": "NMI" },
        "events": [ /* event objects */ ],
        "created_at": "2024-12-10T09:00:00Z"
      }
    ]
  }
  ```
</ResponseExample>

***

### Get Click Details

```
GET /api/brands/{brand}/clicks/{click_code}
```

<ParamField type="string">
  Session ID or click code
</ParamField>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "click-es-doc-abc",
    "session_id": "sess-xyz-123",
    "ip_address": "203.0.113.50",
    "url": "/checkout",
    "funnel_id": 5,
    "domain": { /* domain */ },
    "events": [ /* events */ ]
  }
  ```

  ```json 404 theme={null}
  { "message": "Not found" }
  ```
</ResponseExample>

***

### Get Session Details

Returns geo data and the full sequence of events for a visitor session.

```
GET /api/brands/{brand}/clicks/session/{sessionId}
```

<ParamField type="string">
  Session ID
</ParamField>

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/clicks/session/sess-xyz-123 \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "geoData": {
      "lat": 34.052,
      "lon": -118.244,
      "city": "Los Angeles",
      "region": "CA",
      "country": "US",
      "zip": "90001",
      "ip_address": "203.0.113.50"
    },
    "events": [
      {
        "type": "page_view",
        "url": "/checkout",
        "timestamp": "2024-12-10T09:00:00Z",
        "data": {}
      },
      {
        "type": "add_to_cart",
        "timestamp": "2024-12-10T09:01:30Z",
        "data": { "product_id": 3 }
      }
    ],
    "domains": {
      "7": "https://checkout.mybrand.com"
    }
  }
  ```

  ```json No data found theme={null}
  {
    "geoData": [],
    "events": []
  }
  ```
</ResponseExample>

***

### Export Clicks

Queue a CSV export of click records.

```
POST /api/brands/{brand}/clicks/export
```

<ParamField type="array">
  Filter conditions (same as list query params)
</ParamField>

<ParamField type="array">
  Limit export to specific click codes
</ParamField>

<ParamField type="array">
  Columns to include in the export
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/clicks/export \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"columns": ["session_id", "ip_address", "url", "created_at"]}'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "message": "Export started. You will receive an email when it is ready."
  }
  ```
</ResponseExample>

***

## Session Replays

Session replays capture mouse movements, clicks, and scroll events for visitor sessions.

### List Session Replays

```
GET /api/brands/{brand}/replays
```

<ParamField type="string">
  Session ID to retrieve replays for
</ParamField>

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "id": "replay-doc-abc",
      "session_id": "sess-xyz-123",
      "page_session_id": "page-sess-456"
    }
  ]
  ```
</ResponseExample>

***

### Get Session Replay

Retrieve the full recorded event stream for a session.

```
GET /api/brands/{brand}/replays/{sessionId}
```

<ParamField type="string">
  Session replay document ID (from the list endpoint)
</ParamField>

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id}/replays/replay-doc-abc \
  -H "EF-Access-Key: your_api_key_here"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "replay-doc-abc",
    "session_id": "sess-xyz-123",
    "page_session_id": "page-sess-456",
    "url": "/checkout",
    "duration_ms": 45000,
    "viewport_width": 1440,
    "viewport_height": 900,
    "events": [
      { "type": "mousemove", "x": 100, "y": 200, "ts": 1500 },
      { "type": "click", "x": 300, "y": 400, "ts": 2300, "target": "button#buy-now" },
      { "type": "scroll", "scrollY": 800, "ts": 5000 }
    ]
  }
  ```
</ResponseExample>

<Warning>
  If the session replay document does not exist in Elasticsearch, the response may produce an error. Always use `session_id` values returned from the list endpoint.
</Warning>

***

## Short Links

Short links create trackable redirects for marketing campaigns, affiliate links, and social sharing.

### Generate Short Link

```
POST /api/brands/{brand}/short-links/generate
```

<ParamField type="string">
  The destination URL the short link will redirect to. Must be a valid URL.
</ParamField>

```bash cURL theme={null}
curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/short-links/generate \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"destination_url": "https://checkout.mybrand.com/offer?utm_source=email"}'
```

```python Python theme={null}
import requests

response = requests.post(
    f'https://app.elasticfunnels.io/api/brands/{brand_id}/short-links/generate',
    headers={'EF-Access-Key': 'your_api_key_here'},
    json={'destination_url': 'https://checkout.mybrand.com/offer?utm_source=email'}
)
data = response.json()
print(f"Short URL: {data['url']}")  # https://go.mybrand.com/g/abc123
```

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "code": "abc123",
    "url": "https://go.mybrand.com/g/abc123"
  }
  ```

  ```json 422 Invalid URL theme={null}
  {
    "errors": {
      "destination_url": ["Invalid URL"]
    }
  }
  ```
</ResponseExample>

***

## Notes

<Info>
  * Click data is stored in **Elasticsearch** by default, but accounts with ClickHouse enabled use a separate engine — both are queried transparently via the same API
  * The session replay `events` array is stored as a compressed/encoded string in Elasticsearch and decoded automatically before being returned
  * Short links are served from the `SHORT_URL_DOMAIN` configured for your account (e.g. `go.yourdomain.com`)
  * The clicks `index` endpoint always returns **30 results per page** regardless of `per_page` parameter
</Info>


# Errors & Status Codes
Source: https://docs.elasticfunnels.io/api-reference/errors

Understanding API error responses

## Error Response Format

Most failed requests return a JSON body. The **most common** validation/auth shape is:

```json theme={null}
{
  "message": "Error message describing what went wrong",
  "errors": {
    "field_name": [
      "Specific validation error for this field"
    ]
  }
}
```

### Alternate shapes (also used in production)

Endpoints are not fully normalized to one schema. Also handle these when present:

| Pattern | Typical status | Example |
| - | - | - |
| `message` only | 401, 404 | `{ "message": "Invalid API key or brand access denied" }` |
| `error` string | 403, 404, 409 | `{ "error": "component_in_use", "message": "...", "usage_count": 3 }` |
| `success: false` | 409 | `{ "success": false, "message": "...", "code": "revision_conflict" }` |
| `plan_error` | 403, 422 | `{ "error": "Upgrade required...", "plan_error": { ... } }` |
| Laravel `errors` only | 422 | `{ "errors": { "domain": ["The domain has already been taken."] } }` |
| Non-JSON / HTML | 302, 500 | Session redirect to login, or proxy error pages — check `Content-Type` |

<Info>
  Always branch on **HTTP status code** first, then parse JSON if `Content-Type` includes `application/json`. Log the raw response body when debugging unknown failures.
</Info>

## HTTP Status Codes

ElasticFunnels uses conventional HTTP response codes to indicate the success or failure of an API request.

### Success Codes

<ResponseField name="200" type="OK">
  The request was successful.
</ResponseField>

<ResponseField name="201" type="Created">
  The resource was successfully created.
</ResponseField>

<ResponseField name="204" type="No Content">
  The request was successful but there's no content to return (typically for DELETE requests).
</ResponseField>

### Client Error Codes

<ResponseField name="400" type="Bad Request">
  The request was malformed or contains invalid parameters.
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Authentication failed. Check your API key.
</ResponseField>

<ResponseField name="403" type="Forbidden">
  You don't have permission to access this resource.
</ResponseField>

<ResponseField name="404" type="Not Found">
  The requested resource doesn't exist.
</ResponseField>

<ResponseField name="422" type="Unprocessable Entity">
  Validation failed. Check the `errors` field in the response.
</ResponseField>

<ResponseField name="429" type="Too Many Requests">
  Rate limit exceeded. Slow down your requests.
</ResponseField>

### Server Error Codes

<ResponseField name="500" type="Internal Server Error">
  Something went wrong on our end. Please contact support if this persists.
</ResponseField>

<ResponseField name="503" type="Service Unavailable">
  The service is temporarily unavailable. Please try again later.
</ResponseField>

## Common Error Scenarios

### Authentication Errors

#### Invalid API Key

```json theme={null}
{
  "message": "Invalid API key"
}
```

**Status Code:** `401`

**Solution:** Check that your API key is correct and hasn't been regenerated.

#### No Brand Access

```json theme={null}
{
  "message": "Invalid API key or brand access denied"
}
```

**Status Code:** `401`

**Solution:** Ensure your API key has access to the specified brand/project.

### Validation Errors

#### Missing Required Fields

```json theme={null}
{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name field is required."
    ],
    "price": [
      "The price field is required."
    ]
  }
}
```

**Status Code:** `422`

**Solution:** Include all required fields in your request.

#### Invalid Field Values

```json theme={null}
{
  "message": "The given data was invalid.",
  "errors": {
    "price": [
      "The price must be a number.",
      "The price must be at least 0."
    ],
    "status": [
      "The selected status is invalid."
    ]
  }
}
```

**Status Code:** `422`

**Solution:** Ensure field values meet the requirements (correct type, valid options, etc.).

### Permission Errors

#### Insufficient Permissions

```json theme={null}
{
  "message": "You don't have permission to perform this action."
}
```

**Status Code:** `403`

**Solution:** This action requires higher permissions (e.g., Admin or Owner role).

### Resource Errors

#### Resource Not Found

```json theme={null}
{
  "message": "Resource not found"
}
```

**Status Code:** `404`

**Solution:** Check that the resource ID is correct and the resource exists.

### Rate Limiting

#### Too Many Requests

```json theme={null}
{
  "message": "Too many requests. Please slow down."
}
```

**Status Code:** `429`

**Solution:** Implement exponential backoff or reduce request frequency.

## Best Practices for Error Handling

<CardGroup>
  <Card title="Check Status Codes" icon="check">
    Always check the HTTP status code before parsing the response
  </Card>

  <Card title="Handle Validation Errors" icon="triangle-exclamation">
    Display validation errors to users in a friendly format
  </Card>

  <Card title="Implement Retry Logic" icon="rotate">
    Retry failed requests with exponential backoff for 5xx errors
  </Card>

  <Card title="Log Errors" icon="file-lines">
    Log error responses for debugging and monitoring
  </Card>
</CardGroup>

## Example Error Handling

Here are examples of proper error handling in different languages:

### JavaScript

```javascript theme={null}
try {
  const response = await fetch(
    'https://app.elasticfunnels.io/api/brands/123/pages',
    {
      method: 'POST',
      headers: {
        'EF-Access-Key': 'your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ name: 'New Page' })
    }
  );

  if (!response.ok) {
    const error = await response.json();
    
    if (response.status === 401) {
      console.error('Authentication failed:', error.message);
    } else if (response.status === 422) {
      console.error('Validation errors:', error.errors);
    } else {
      console.error('API error:', error.message);
    }
    
    throw new Error(error.message);
  }

  const data = await response.json();
  console.log('Success:', data);
} catch (error) {
  console.error('Request failed:', error);
}
```

### Python

```python theme={null}
import requests

try:
    response = requests.post(
        'https://app.elasticfunnels.io/api/brands/123/pages',
        headers={
            'EF-Access-Key': 'your_api_key_here',
            'Content-Type': 'application/json'
        },
        json={'name': 'New Page'}
    )
    
    response.raise_for_status()
    data = response.json()
    print('Success:', data)
    
except requests.exceptions.HTTPError as e:
    error_data = e.response.json()
    
    if e.response.status_code == 401:
        print('Authentication failed:', error_data['message'])
    elif e.response.status_code == 422:
        print('Validation errors:', error_data['errors'])
    else:
        print('API error:', error_data['message'])
        
except requests.exceptions.RequestException as e:
    print('Request failed:', str(e))
```

### PHP

```php theme={null}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://app.elasticfunnels.io/api/brands/123/pages');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'EF-Access-Key: your_api_key_here',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['name' => 'New Page']));

$response = curl_exec($ch);
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

if ($statusCode >= 200 && $statusCode < 300) {
    echo 'Success: ' . print_r($data, true);
} else {
    if ($statusCode === 401) {
        echo 'Authentication failed: ' . $data['message'];
    } elseif ($statusCode === 422) {
        echo 'Validation errors: ' . print_r($data['errors'], true);
    } else {
        echo 'API error: ' . $data['message'];
    }
}
```

## Need Help?

If you encounter persistent errors or need assistance:

<Card title="Contact Support" icon="life-ring" href="mailto:support@elasticfunnels.io">
  [support@elasticfunnels.io](mailto:support@elasticfunnels.io)
</Card>


# API Introduction
Source: https://docs.elasticfunnels.io/api-reference/introduction

Getting started with the ElasticFunnels API

## Welcome to ElasticFunnels API

The ElasticFunnels API allows you to programmatically manage your projects, pages, products, conversions, and analytics. Our API is organized around REST principles with predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes.

<Note>
  All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
</Note>

## Base URL

All API endpoints are relative to the base URL:

```
https://app.elasticfunnels.io/api
```

## Authentication

The ElasticFunnels API uses API keys for authentication. You can generate and manage your API keys from your project settings under the API tab.

<Card title="Authentication Guide" icon="key" href="/api-reference/authentication">
  Learn how to authenticate your API requests
</Card>

## Making Your First Request

Here's a simple example to get your project details:

```bash cURL theme={null}
curl https://app.elasticfunnels.io/api/brands/{brand_id} \
  -H "EF-Access-Key: your_api_key_here"
```

```javascript JavaScript theme={null}
const response = await fetch('https://app.elasticfunnels.io/api/brands/{brand_id}', {
  headers: {
    'EF-Access-Key': 'your_api_key_here'
  }
});

const brand = await response.json();
```

```python Python theme={null}
import requests

response = requests.get(
    'https://app.elasticfunnels.io/api/brands/{brand_id}',
    headers={'EF-Access-Key': 'your_api_key_here'}
)

brand = response.json()
```

## Rate Limits

<Info>
  Rate limiting information will be added in a future update. Currently, reasonable use is expected.
</Info>

## Support

Need help with the API? Contact our support team:

<Card title="Email Support" icon="envelope" href="mailto:support@elasticfunnels.io">
  [support@elasticfunnels.io](mailto:support@elasticfunnels.io)
</Card>


# Quick Start Guide
Source: https://docs.elasticfunnels.io/api-reference/quick-start

Get up and running with the ElasticFunnels API in minutes

## 5-Minute Setup

Follow these steps to make your first API request:

<Steps>
  <Step title="Generate Your API Key">
    1. Log in to your ElasticFunnels account
    2. Navigate to **Settings** → **API**
    3. Click **Generate API Key**
    4. Copy and securely store your key
  </Step>

  <Step title="Find Your Brand ID">
    Your brand (project) ID is in the URL when you're viewing your project:

    ```
    https://app.elasticfunnels.io/123/analytics
                                    ^^^
                                 Brand ID
    ```
  </Step>

  <Step title="Make Your First Request">
    Test your authentication by fetching your project details:

    ```bash theme={null}
    curl https://app.elasticfunnels.io/api/brands/{brand_id} \
      -H "EF-Access-Key: your_api_key_here"
    ```
  </Step>

  <Step title="Start Building">
    You're ready! Explore the endpoints documentation to build your integration.
  </Step>
</Steps>

## Common Use Cases

### Sync Conversions to Your CRM

Automatically sync new orders to your CRM or analytics platform:

```javascript theme={null}
// Fetch recent conversions
const response = await fetch(
  'https://app.elasticfunnels.io/api/brands/123/conversions?page=1&per_page=50',
  {
    headers: {
      'EF-Access-Key': 'your_api_key_here'
    }
  }
);

const { data } = await response.json();

// Process each conversion
for (const order of data) {
  await syncToCRM({
    email: order.customer_email,
    name: order.customer_name,
    revenue: order.total,
    order_id: order.code
  });
}
```

### Monitor Split Test Performance

Check split test results programmatically:

```python theme={null}
import requests

# Get split test results
response = requests.get(
    'https://app.elasticfunnels.io/api/brands/123/split-tests/456',
    headers={'EF-Access-Key': 'your_api_key_here'}
)

split_test = response.json()

# Find the winning variant
winner = next(v for v in split_test['variants'] if v['is_winner'])
print(f"Winner: {winner['name']} with {winner['conversion_rate']}% CR")

# Alert if improvement is significant
if winner['conversion_rate'] > 5.0:
    send_slack_notification(f"🎉 Split test winner: {winner['conversion_rate']}% CR!")
```

### Bulk Create Pages from Templates

Automate page creation for new campaigns:

```javascript theme={null}
const campaigns = [
  { name: 'Summer Sale', slug: 'summer-sale' },
  { name: 'Black Friday', slug: 'black-friday' },
  { name: 'New Year', slug: 'new-year' }
];

for (const campaign of campaigns) {
  const response = await fetch(
    'https://app.elasticfunnels.io/api/brands/123/pages',
    {
      method: 'POST',
      headers: {
        'EF-Access-Key': 'your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: campaign.name,
        slug: campaign.slug,
        type: 'landing',
        status: 'inactive'
      })
    }
  );
  
  const page = await response.json();
  console.log(`Created page: ${page.url}`);
}
```

### Daily Revenue Report

Generate and email daily performance reports:

```python theme={null}
from datetime import date, timedelta
import requests

# Get yesterday's metrics
yesterday = date.today() - timedelta(days=1)

response = requests.get(
    f'https://app.elasticfunnels.io/api/brands/123/analytics/metrics',
    params={
        'start_date': yesterday.isoformat(),
        'end_date': yesterday.isoformat()
    },
    headers={'EF-Access-Key': 'your_api_key_here'}
)

metrics = response.json()['metrics']

# Format report
report = f"""
Daily Performance Report - {yesterday}

📊 Visitors: {metrics['visitors']:,}
📧 Leads: {metrics['leads']:,}
🛒 Orders: {metrics['orders']:,}
💰 Revenue: ${metrics['revenue']:,.2f}
📈 AOV: ${metrics['aov']:.2f}
🎯 Conversion Rate: {metrics['conversion_rate']:.2f}%
"""

send_email(to='team@example.com', subject='Daily Report', body=report)
```

### Export Conversion Data

Export conversion data for analysis in your BI tool:

```bash theme={null}
# Request export
curl -X POST https://app.elasticfunnels.io/api/brands/123/conversions/export \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2024-12-01",
    "end_date": "2024-12-31"
  }'

# Response includes download URL
{
  "message": "Export is being processed",
  "export_id": "exp_abc123",
  "download_url": "https://app.elasticfunnels.io/api/brands/123/exports/exp_abc123/download/token"
}

# Download the file
curl -O "https://app.elasticfunnels.io/api/brands/123/exports/exp_abc123/download/token"
```

## SDKs and Libraries

While ElasticFunnels doesn't provide official SDKs yet, the API works with any HTTP client library:

<CardGroup>
  <Card title="JavaScript" icon="js">
    * `fetch` (native)
    * `axios`
    * `node-fetch`
  </Card>

  <Card title="Python" icon="python">
    * `requests`
    * `httpx`
    * `aiohttp`
  </Card>

  <Card title="PHP" icon="php">
    * `cURL`
    * `Guzzle`
    * `HTTP Client`
  </Card>
</CardGroup>

## Rate Limiting Best Practices

<Info>
  While rate limits aren't strictly enforced currently, follow these best practices for optimal performance:
</Info>

1. **Batch Requests**: Fetch multiple items in one request when possible
2. **Cache Responses**: Cache data that doesn't change frequently
3. **Use Pagination**: Don't try to fetch all records at once
4. **Implement Backoff**: Retry failed requests with exponential backoff

Example retry logic:

```javascript theme={null}
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      if (response.ok) {
        return await response.json();
      }
      
      // If rate limited, wait before retry
      if (response.status === 429) {
        const waitTime = Math.pow(2, attempt) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      
      throw new Error(`HTTP ${response.status}`);
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
    }
  }
}
```

## Next Steps

<CardGroup>
  <Card title="Browse Endpoints" icon="code" href="/api-reference/endpoints/brands">
    Explore all available API endpoints
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/api-reference/errors">
    Learn how to handle errors properly
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Deep dive into API authentication
  </Card>

  <Card title="Get Support" icon="life-ring" href="mailto:support@elasticfunnels.io">
    Contact our support team
  </Card>
</CardGroup>


# Actions
Source: https://docs.elasticfunnels.io/backend-scripts/actions

Side-effect functions: session, cookies, redirects, response control, headers, and template variables.

Action functions let your backend script perform side-effects — set session data, cookies, redirect the visitor, inject template variables, or send custom responses.

## Session

Read and write values in the visitor's server-side session.

```javascript theme={null}
session.set('my_key', 'my_value');
session.set('visit_count', 5);

var count = session.get('visit_count');  // 5
var missing = session.get('nonexistent'); // null
```

Session values set here are immediately available to funnel script rules that run after the backend script.

<Warning>
  Session keys and values should be simple types (strings, numbers, booleans). Complex objects are serialized as JSON internally.
</Warning>

<Note>
  For security, some session keys are reserved and cannot be read or written via `session.get()` / `session.set()`. Use your own key names (e.g. `my_key`, `visit_count`) for custom data.
</Note>

### `session.setCustomer(fields)`

Establish an authenticated customer session from a custom login flow — magic link, external OTP, SSO callback, or any mechanism outside the built-in purchase pipeline. Writes the runtime's canonical customer fields (`is_customer`, `email`, `customer_id`, `customer`) so downstream pages, template variables, and access rules see the visitor as logged in.

```javascript theme={null}
// Verify a one-time code your app generated...
var code = getVariable('submitted_code');
var email = getVariable('submitted_email');
var ok = verifyMyOtp(email, code);

if (ok) {
  session.setCustomer({ email: email, name: 'Jane Doe' });
  redirect('/dashboard');
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `email` | string | yes | The customer's email (must contain `@`). |
| `name` | string | no | Full display name. If omitted, derived from `first_name` + `last_name`. |
| `first_name` | string | no | First name. Merged into `session.customer.first_name`. |
| `last_name` | string | no | Last name. Merged into `session.customer.last_name`. |
| `id` | any | no | Internal customer id. When set, also writes `session.customer_id`. |

Returns `true` on success, `false` on invalid input or quota exhaustion.

<Note>
  `setCustomer` merges over any existing `session.customer` object, so tracking fields such as `total`, `currency`, or `order_ids` set by earlier checkout flows are preserved.
</Note>

### `session.getToken(ttlSeconds?)` / `session.setFromToken(token)`

Mint and consume short-lived encrypted tokens that carry the current customer identity across brand-owned domains. Used for cross-domain session continuity — see [Cross-domain session handoff](/guides/cross-domain-session-handoff) for the full protocol and a worked example.

```javascript theme={null}
// On the source domain: mint a 60-second token
var token = await session.getToken();        // null if no customer
var url = 'https://app.example.com/welcome?ef_session=' + encodeURIComponent(token);
redirect(url);

// On the destination domain: most of the time you don't need this — the
// EF runtime auto-consumes `?ef_session=<token>` on every request. Call
// setFromToken() manually only if you need to consume a token from a
// header, body, or non-query-string location.
var ok = await session.setFromToken(headerToken);
```

`session.getToken(ttlSeconds?)` returns the token string (or `null` if the session has no customer). `ttlSeconds` defaults to `60` and is capped at `600`.

`session.setFromToken(token)` returns `true` on success, `false` on any failure (tamper, expiry, replay, wrong brand). It never throws.

## Cookies

Set or delete cookies on the visitor's browser.

```javascript theme={null}
cookie.set('promo_seen', 'true', { maxAge: 3600, path: '/' });
cookie.delete('old_cookie');
```

### `cookie.set(name, value, options?)`

| Option | Type | Description |
| - | - | - |
| `maxAge` | number | Cookie lifetime in **seconds** |
| `path` | string | Cookie path (default: `'/'`) |

### `cookie.delete(name)`

Clears the cookie by name.

<Note>
  Some cookie names are reserved and cannot be set or deleted. Use your own cookie names for custom data.
</Note>

<Note>
  Visitor **tags** are cookies too, but do not set them with `cookie.set()` — use [`addTag()` / `hasTag()` / `removeTag()`](/backend-scripts/tags), which write the naming both the funnel nodes and the browser expect.
</Note>

## Redirect

Redirect the visitor to a different URL. This **stops** page rendering — the visitor is immediately sent to the new URL.

```javascript theme={null}
redirect('/login');           // 302 temporary redirect
redirect('/new-page', 301);   // 301 permanent redirect
redirect('https://example.com/page'); // external redirect
```

<Note>
  When `redirect()` is called, the entire funnel flow and page rendering are skipped. The visitor receives only the redirect response.
</Note>

<Warning>
  Only relative paths (`/path`) and `http://` / `https://` URLs are allowed. Other schemes (e.g., `javascript:`, `data:`) are blocked for security.
</Warning>

## Template Variables

Inject values into the template engine. These become available as `{{ var.key }}` in page HTML.

```javascript theme={null}
setVariable('discount', '50%');
setVariable('show_banner', true);
setVariable('user_tier', 'premium');
setVariable('user', { name: 'Sam', email: 'sam@example.com' });
setVariable('categories', [
  { slug: 'marketing', name: 'Marketing', courses: [...] },
  { slug: 'design', name: 'Design', courses: [...] },
]);
```

In your page HTML:

```html theme={null}
<h1>Get {{ var.discount }} off!</h1>

@if(var.show_banner)
  <div class="banner">Premium member</div>
@endif

<!-- Objects work too -->
<p>Welcome, {{ var.user.name }}</p>

<!-- Debug: dump the full object as JSON -->
<pre>{{ dump(var.user) }}</pre>
```

<Warning>
  `setVariable('name', value)` stores the value under the `var` namespace. Always access it as **`var.name`** in templates — e.g. `{{ var.name }}`, `{{ dump(var.name) }}`, `@if(var.name)`. Using `{{ name }}` or `{{ dump(name) }}` without the `var.` prefix will **not** find the variable.
</Warning>

### Scoping inside `@foreach`

When you iterate over a variable with `@foreach`, the **loop variable** is its own scope — it does **not** use the `var.` prefix:

```html theme={null}
<!-- var.categories needs the var. prefix (it came from setVariable) -->
@foreach(cat in var.categories)
  <!-- cat is a loop variable — access its properties directly, no var. prefix -->
  <h2>{{ cat.name }}</h2>
  <p>{{ cat.slug }}</p>

  <!-- nested arrays on the loop variable also work directly -->
  @foreach(course in cat.courses)
    <div>{{ course.title }}</div>
  @endforeach
@endforeach
```

In short: `var.` is only for the **top-level** reference to variables set by `setVariable`. Once a value is assigned to a loop variable (`cat`, `course`, etc.), you access its properties directly.

Variables set with `setVariable` take precedence over brand variables with the same key.

## Response Headers

Set custom HTTP response headers.

```javascript theme={null}
setHeader('X-Custom-Header', 'my-value');
setHeader('Cache-Control', 'no-store');
```

<Note>
  For security, certain response headers cannot be set (e.g. those that control cookies, CORS, or connection). Header values are sanitized.
</Note>

## Custom Response

Send a custom response instead of the rendered page. These **stop** page rendering.

### `response.status(code)`

Set the HTTP status code (used with `response.send()` or `response.json()`, or with the normal page render).

```javascript theme={null}
response.status(403);
response.send('<h1>Access Denied</h1>');
```

### `response.json(data)`

Send a JSON response. Skips page rendering.

```javascript theme={null}
response.json({ error: false, user: customer.email });
```

### `response.send(html)`

Send raw HTML. Skips page rendering.

```javascript theme={null}
response.send('<html><body><h1>Maintenance</h1></body></html>');
```

## Logging and errors

`console.log`, `console.info`, `console.warn`, and `console.error` are captured and stored in execution logs. Use them for debugging.

```javascript theme={null}
console.log('Visitor IP:', request.ip);
console.log('Customer:', customer);
```

Logs and errors are visible in the [Debug Window](/debugging/debug-window) (Page Events tab) for the page request. If your script throws an error or times out, the visitor still receives the normal page (no error message is shown); the error is logged there and may be reported to admins.


# Cache
Source: https://docs.elasticfunnels.io/backend-scripts/cache

Brand-scoped key-value cache for backend scripts.

Backend scripts have access to a Redis-backed key-value cache via the `cache` global. Every key is automatically scoped to the current brand — scripts can never read or write keys belonging to another brand.

Values are JSON-serialised, so you can store strings, numbers, booleans, arrays, and plain objects.

## `cache.get(key)`

Retrieve a value from the cache.

```javascript theme={null}
var count = cache.get('page_views');
if (count !== null) {
  setVariable('views', count);
}
```

| Parameter | Type | Description |
| - | - | - |
| `key` | string | Cache key |

**Returns:** The stored value, or `null` if the key does not exist or has expired.

## `cache.set(key, value, ttlSeconds?)`

Store a value in the cache with an optional TTL.

```javascript theme={null}
cache.set('last_visit', new Date().toISOString(), 3600);
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `key` | string | — | Cache key |
| `value` | any | — | Value to store (JSON-serialised) |
| `ttlSeconds` | number | 3600 | Time-to-live in seconds |

**Returns:** `true` on success, `false` if the brand key limit was reached or an error occurred.

## `cache.del(key)`

Delete a key from the cache.

```javascript theme={null}
cache.del('last_visit');
```

| Parameter | Type | Description |
| - | - | - |
| `key` | string | Cache key |

**Returns:** `true` on success.

## `cache.has(key)`

Check whether a key exists in the cache.

```javascript theme={null}
if (cache.has('onboarding_complete')) {
  redirect('/dashboard');
}
```

| Parameter | Type | Description |
| - | - | - |
| `key` | string | Cache key |

**Returns:** `true` if the key exists, `false` otherwise.

## `cache.setIfAbsent(key, value, ttlSeconds?)`

Write a value only if the key does **not** already exist. Useful for debouncing and deduplication.

```javascript theme={null}
var isNew = cache.setIfAbsent('email_sent:' + email, true, 86400);
if (isNew) {
  // First time — send the email
}
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `key` | string | — | Cache key |
| `value` | any | — | Value to store |
| `ttlSeconds` | number | 3600 | Time-to-live in seconds |

**Returns:** `true` if the value was written (key was absent), `false` if the key already existed.

## `cache.increment(key, amount?, ttlSeconds?)`

Atomically increment a numeric value. Creates the key with the given amount if it doesn't exist.

```javascript theme={null}
var views = cache.increment('page:home:views', 1, 86400);
setVariable('view_count', views);
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `key` | string | — | Cache key |
| `amount` | number | 1 | Value to add (can be negative or float) |
| `ttlSeconds` | number | — | Optional TTL to set/refresh |

**Returns:** The new numeric value after incrementing.

<Note>
  **Limits per brand:**

  * **50,000 keys** maximum per brand
  * **512 bytes** maximum value size
  * **1-hour** maximum TTL
  * **20 cache operations** per script execution
</Note>

<Warning>
  Cache keys must match the pattern `[a-zA-Z0-9_.:-]` and be at most 200 characters long. Keys that don't match will throw an error.
</Warning>


# Request Context
Source: https://docs.elasticfunnels.io/backend-scripts/context

Read-only globals available inside backend scripts: request data, customer info, and visitor details.

These globals are injected automatically into every backend script execution. They are **read-only** — you cannot modify them directly.

## `request`

Information about the current HTTP request.

```javascript theme={null}
request.query          // { foo: 'bar', utm_source: 'google' }
request.headers        // see below
request.method         // 'GET' or 'POST'
request.body           // parsed body, JSON or form-urlencoded (POST only, null for GET, max 64 KB)
request.ip             // IPv4 address, e.g. '1.2.3.4'
request.ip6            // IPv6 address (if available)
request.path           // '/my-page'
request.cookies        // { cookie_name: 'value' }
request.is_mobile      // true/false
request.is_tablet      // true/false
```

### `request.body`

When a page receives a `POST` request, the body is parsed and available as `request.body`. Pages accept both GET and POST requests, and the same backend script runs for both, so use `request.method` to distinguish.

```javascript theme={null}
if (request.method === 'POST' && request.body) {
  var data = request.body;
  console.log('Received:', data.name);
}
```

Both JSON (`application/json`) and ordinary form posts
(`application/x-www-form-urlencoded`) are parsed, so a plain HTML `<form>` can
post straight to the page that renders it:

```html theme={null}
<form method="post">
  <input type="email" name="email" required>
  <button type="submit">Notify me</button>
</form>

<script scope="backend">
if (request.method === 'POST' && request.body) {
  setVariable('submitted_email', request.body.email);
}
</script>
```

<Note>
  `multipart/form-data` is **not** parsed on page routes, so a form with that
  `enctype` (including file uploads) arrives with `request.body` as `null`.
</Note>

<Warning>
  The body handed to the script is capped at **64 KB**, well below the request
  size the server itself accepts. A larger payload is dropped silently:
  `request.body` is `null` rather than truncated, and nothing is logged. Guard
  with `if (request.method === 'POST' && request.body)` so a page never assumes
  a body it did not get.
</Warning>

### `request.headers`

A subset of request headers is exposed:

| Key | Description |
| - | - |
| `user-agent` | Browser/device user-agent string |
| `referer` | Referring URL |
| `accept-language` | Visitor's language preferences |
| `host` | Domain the request was made to |

<Warning>
  Full request headers are not exposed to prevent leaking internal infrastructure details (e.g. proxy headers, auth tokens).
</Warning>

## `customer`

The current customer object from the session, or `null` if no customer is set. Populated after checkout or check-order login.

```javascript theme={null}
customer.name
customer.email
customer.first_name
customer.last_name
customer.phone
customer.order_id
customer.order_ids           // array of order objects
customer.order_item
customer.order_item_name
customer.conversion_code
customer.payment_provider
customer.billing_first_name
customer.billing_last_name
customer.billing_address
customer.billing_city
customer.billing_state
customer.billing_zip
customer.billing_country
customer.shipping_first_name
customer.shipping_last_name
customer.shipping_address
customer.shipping_city
customer.shipping_state
customer.shipping_zip
customer.shipping_country
```

## `is_customer`

Boolean. `true` if the visitor has an active customer session (completed a purchase or logged in via check-order).

```javascript theme={null}
if (!is_customer) {
  redirect('/sales-page');
}
```


# Data Functions
Source: https://docs.elasticfunnels.io/backend-scripts/data-functions

Query customers, orders, products, courses, blog, and more from your backend scripts.

Backend scripts expose the same data functions available in the template engine, so you can query your brand data and use the results for logic, not just display.

All data functions that hit the database are **asynchronous** under the hood, but they look synchronous in your code — just call them and use the return value directly. Pure-computation helpers (like `formatPrice`, `productSavings`) are truly synchronous.

## Customer

### `getCustomer()`

Returns the full current customer object from the session (same as the `customer` global).

```javascript theme={null}
var c = getCustomer();
if (c && c.email) {
  console.log('Customer:', c.email);
}
```

### `getUser()`

Returns a lightweight `{ name, email }` object for the current session customer.

```javascript theme={null}
var user = getUser();
if (user.email) {
  setVariable('greeting', 'Welcome, ' + user.name);
}
```

## Translations

Backend scripts use the same **resolved locale** as page templates (`req.locale` after host resolution). That value comes from route/query/session/domain/brand/`Accept-Language` and is then **snapped** to a row in Advanced → Translations when the brand has languages configured. See [Internationalization](/pages/internationalization) for precedence and template helpers (`t()`, `| t`, and related).

Most translation helpers are **async** in the sandbox — use `await`.

### `getLocale()`

Returns the active resolved locale code for this request (same as `req.locale`), e.g. `'en'` or `'ro'`.

```javascript theme={null}
if ((await getLocale()) === 'ro') {
  setVariable('currency_symbol', 'lei');
}
```

### `getLocales()`

Returns the list of locale **codes** configured for the brand (admin sort order). Empty array when the brand has no translation languages.

```javascript theme={null}
var available = await getLocales(); // ['en', 'ro']
```

### `getDefaultLocale()`

Returns the brand **default** language code, or the first language by sort order, or `''` when none exist.

```javascript theme={null}
if (await getDefaultLocale() === 'en') {
  setVariable('show_usd', true);
}
```

### `t(key, params?)`

**Async.** Tries the **brand** dictionary first for `key`, then built-in locale JSON. Optional `params` is a plain object for `{{ name }}`-style interpolation in **built-in** strings — not a fallback text argument. This is the default choice in backend scripts for the same keys you use with **`t()`** or **`| t`** in templates.

```javascript theme={null}
var label = await t('title.greeting');
var hero = await t('hero.title');
var cta = await t('checkout.cta');
setVariable('hero_title', hero);
setVariable('checkout_cta', cta);
var pct = await t('product.savings_percent', { percent: 20 });
setVariable('savings_label', pct);
```

### `getTranslation(key)`

**Async.** Reads **only** the brand dictionary (no built-in fallback); returns `''` if the key is missing. Prefer **`t()`** unless you explicitly need that behavior.

### `getTranslations()`

Returns a **plain object** copy of every `key → value` for the active resolved language (empty object when the brand has no entries).

```javascript theme={null}
var all = await getTranslations();
console.log(Object.keys(all).length);
```

### `getResolvedLanguage()`

Returns the **snapped** language code used for brand translations (e.g. `'ro'`), or the raw locale hint when the brand has no translation languages configured.

```javascript theme={null}
var code = await getResolvedLanguage();
if (code === 'de') {
  setVariable('region', 'EU');
}
```

## Orders

### `getOrders(sortBy?, limit?)`

Fetch the current customer's orders from the database.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `sortBy` | string | `'newest'` | `'newest'` or `'oldest'` |
| `limit` | number | `50` | Max orders to return (max 1000) |

```javascript theme={null}
var orders = getOrders('newest', 10);

if (orders.length > 0) {
  setVariable('has_orders', true);
  setVariable('latest_order', orders[0].order_number);

  console.log('Found', orders.length, 'orders');
}
```

Each order object contains:

```javascript theme={null}
{
  order_number: 'ORD-12345',
  created_at: '2025-01-15T10:30:00Z',
  billing_address: '...',
  billing_city: '...',
  billing_state: '...',
  billing_zip: '...',
  billing_country: 'US',
  shipping_address: '...',
  shipping_city: '...',
  shipping_state: '...',
  shipping_zip: '...',
  shipping_country: 'US',
  currency: 'USD',
  customer_name: 'John Doe',
  customer_email: 'john@example.com',
  products: [
    { name: 'Premium Plan', price: 49.99, quantity: 1, image_url: '...', currency_code: 'USD' }
  ],
  tracking: [
    { tracking_number: '1Z999AA10123456784', tracking_url: '...', carrier: 'UPS' }
  ]
}
```

### `getOrder(code)`

Fetch **one** order for the current customer. Same scope as `getOrders`. The `code` argument is required: public order ID (`order_number`), internal `order_id`, or conversion `code`. Returns `null` if not found.

```javascript theme={null}
var order = getOrder(request.query.order);
if (order) {
  setVariable('order', order);
}
```

See [Showing order details](/members-area/order-details) for template examples.

### `getOrderFulfillment(code)`

Returns an **allowlisted** fulfillment **summary** for a single order. Same `code` rules as `getOrder`. Use this for status labels and timestamps shown to customers.

Returns `null` when the order exists but has **no** fulfillment record yet (no integration / not scheduled), or when the order is not found.

**Returned fields** (only these; raw `fulfillment_provider_response` and `fulfillment_order_data` are never exposed):

| Field | Type | Description |
| - | - | - |
| `status` | string \| null | Normalized: `pending`, `scheduled`, `sent`, `failed`, `skipped`, `cancelled`, or `unknown` |
| `provider_order_id` | string \| null | External reference from the fulfillment provider when stored on the conversion |
| `integration_name` | string \| null | Display name of the fulfillment integration |
| `scheduled_at` | string \| null | ISO timestamp when processing was scheduled |
| `sent_at` | string \| null | ISO timestamp when the order was sent to the provider |
| `failed_at` | string \| null | ISO timestamp on failure |
| `cancelled_at` | string \| null | ISO timestamp if cancelled |
| `error_message` | string \| null | Truncated message safe for display (max 200 chars) |

```javascript theme={null}
var f = getOrderFulfillment(request.query.order);
if (f) {
  setVariable('fulfillment', f);
}
```

### `getOrderFulfillments()`

Takes **no arguments**. Returns **all** tracking-style rows for the **current customer** across their orders (up to the same order cap as `getOrders` with limit 1000, newest first). Each row includes `order_number` so you can link to an order detail page.

Duplicate `(order_number, tracking_number)` pairs are removed.

**Returned fields per row:**

| Field | Type | Description |
| - | - | - |
| `order_number` | string | Public order id for this shipment |
| `order_date` | string \| null | Order `created_at` (ISO) |
| `tracking_number` | string | Tracking number |
| `tracking_url` | string | Tracking link (e.g. 17track when generated) |
| `carrier` | string | Carrier name |

```javascript theme={null}
var shipments = getOrderFulfillments();
setVariable('shipments', shipments);
```

<Tip>
  These APIs return **filtered** data only. Full provider API responses and internal fulfillment payloads are not available in backend scripts.
</Tip>

## Bonus Products

### `getBonusProducts()`

Fetch the current customer's bonus products — digital downloads and extras they received as part of a purchase. Returns a deduplicated list of bonus items from all the customer's orders.

```javascript theme={null}
var bonuses = getBonusProducts();

if (bonuses.length > 0) {
  setVariable('bonuses', bonuses);
  setVariable('has_bonuses', true);
}
```

Each bonus object contains:

```javascript theme={null}
{
  id: 123,                        // product ID (from brand_products)
  code: 'bonus-ebook',            // product code
  title: 'Free Bonus eBook',      // product title
  description: 'A bonus guide…',  // product description
  image_url: 'https://…/img.jpg', // product image
  bonus_url: 'https://…/file',    // download URL
  price: 0,                       // price (typically 0 for bonuses)
  type: 'digital',                // product type
  classification: 'bonus'         // product classification
}
```

`bonus_url` is the public download URL exposed to backend scripts. Internally, it comes from the saved conversion line when available, and otherwise falls back to the current bonus product download URL from the catalog.

Bonus products are identified by conversion line items where `is_bonus = true`. The function enriches each item with full product details from the catalog. If the same bonus was granted across multiple purchases, it appears only once.

Scoped to the **current session** (email and/or session id): if the visitor is not identified, the list is empty.

### `getAllBonusProducts()`

Returns **all** bonus-classified products in the brand **catalog** (`classification: bonus`). This is **not** limited to what the current customer earned; it does not check orders or conversions.

Object shape matches `getBonusProducts()` (including `title`, `bonus_url`, etc.). For catalog-only rows, `bonus_url` is the product's stored download URL.

```javascript theme={null}
var catalogBonuses = getAllBonusProducts();
setVariable('all_bonus_skus', catalogBonuses);
```

<Tip>
  For the same filter but the **full product** shape (price, currency, `merchant_product_ids`, the normalized `product_files` array, etc.), use `getProducts({ classification: 'bonus' })` instead.
</Tip>

### `getPurchasedProducts(sortBy?, limit?)`

Customer-scoped helper for **member-area "My Library" pages**. Returns every product the current customer has purchased, fully catalog-enriched, with **same-order bonuses already attached** under `included_bonuses[]` and a pre-rolled-up `downloads[]` array (each entry tagged with `kind`).

This replaces the manual recipe of:

* calling `getSessionOrders` + `getAllProducts` + `getBonusProducts` separately,
* joining order lines back to the catalog by code,
* guessing which bonuses go with which product by matching strings in titles.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `sortBy` | string | `'newest'` | `'newest'` or `'oldest'` — controls which purchase wins when the same product appears in multiple orders. |
| `limit` | number | `50` | Max orders considered when scanning the customer's history (max 1000). |

```javascript theme={null}
var purchasedProducts = getPurchasedProducts('newest');
setVariable('purchased_products', purchasedProducts);
```

Each purchased product contains:

```javascript theme={null}
{
  id: 100,
  code: 'theta-clear',
  title: 'Theta Clear',           // checkout_title preferred when present
  checkout_title: '',
  description: '...',
  image: 'https://cdn/theta.png',
  type: 'digital',
  classification: 'main',
  price: 39,                       // catalog price
  retail_price: 99,
  currency: 'USD',

  // Decorated catalog fields (same shape as getProducts)
  product_files: [ /* normalized file rows with `kind` */ ],
  digital_files: [ /* product_files filtered by type='digital' */ ],
  bonus_files:   [ /* product_files filtered by type='bonus' */ ],
  bonus_file: 'https://cdn/...',
  digital_file: 'https://cdn/...',
  primary_download_url: 'https://cdn/...',

  // Pre-rolled-up downloads — one flat list, deduped by URL, each tagged
  // with kind ('audio' | 'video' | 'document' | 'image' | 'archive' | 'file').
  // Use this instead of walking product_files / digital_files / bonus_files
  // by hand. See the productDownloads helper section above.
  downloads: [
    { url: '...', title: 'Theta Clear Vocal Guidance', kind: 'audio',
      purpose: 'digital', extension: 'mp3', mime_type: 'audio/mpeg',
      size: null, is_primary: true, sort_order: 0 },
  ],

  // Purchase context (flat — matches the fields used in member-area templates)
  order_number: 'A0FZ2V0A',
  conversion_code: 'CONV-1',
  created_at: '2026-04-28T10:00:00Z',
  line_price: 39,                  // amount paid for this line
  line_currency: 'USD',
  quantity: 1,
  has_shipping: false,             // true if the order has a shipping address

  // Bonuses received in the SAME order — every is_bonus line, no string
  // filtering. Each entry is catalog-enriched and carries its own
  // `downloads[]` rollup plus a direct `bonus_url`.
  included_bonuses: [
    {
      id: 200,
      code: 'integration-journal',
      title: 'The Theta Clear Integration Journal',
      classification: 'bonus',
      bonus_url: 'https://cdn/journal.pdf',
      downloads: [ /* same shape as above */ ],
      // ...full catalog fields
    },
    // ... all other bonus lines from the same order
  ]
}
```

**Bonus attribution rule:** every `is_bonus` line in an order is attached to every main line of that same order. This matches how funnels actually deliver bonuses (the bonuses come with the offer, not with one specific catalog item). It also avoids the silent-drop bug of older recipes that filtered bonuses by title keywords.

**Dedup rule:** one entry per product (keyed by id, then code). When the same product appears in multiple orders, the order matching the `sortBy` direction wins (newest purchase for `'newest'`). Bonuses come from the kept order.

```javascript theme={null}
// Member-area library — render every purchased product with its bonuses
// and downloads already prepared. No string heuristics, no manual joins.
var library = getPurchasedProducts('newest');

setVariable('library', library);
setVariable('library_count', library.length);
setVariable('has_library', library.length > 0);
```

Scoped to the **current session**: returns `[]` when the visitor is not identified.

## Subscriptions

Customer-scoped recurring billing functions. All operations are restricted to subscriptions belonging to the **current session customer** (matched by email) — a script can never read or modify another customer's subscription.

Write functions return `{ ok: boolean, error?: string, ...rest }` and **never throw** on validation failure. They enforce status transitions automatically (e.g. only `active` can be paused or skipped, only `paused` can be resumed, already-canceled cannot be canceled again).

For full request/response shapes, content-gating examples, and ready-to-use page-based API examples, see [Subscriptions (backend template engine)](/backend-template-engine/subscriptions).

<Note>
  **Per-request cache:** All read helpers (`getSubscriptions`, `getSubscription` with an object arg, `hasSubscription`, `countSubscriptions`) share a per-request cache. The database is queried only once per request — subsequent calls with different filters read from memory.
</Note>

### `getSubscriptions(status?, limit?)`

List the current customer's subscriptions, newest first.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `status` | string | — | Optional filter: `active`, `paused`, `canceled`, `past_due`, or `trial`. Empty / unknown values return all. |
| `limit` | number | `50` | Max subscriptions to return (1–200). |

```javascript theme={null}
var all = getSubscriptions();
var active = getSubscriptions('active', 25);

setVariable('subscriptions', all);
setVariable('has_active_subscription', active.length > 0);
```

Each subscription object contains:

```javascript theme={null}
{
  id: 'sub_abc123',
  status: 'active',                      // active | paused | canceled | past_due | trial
  customer_email: 'jane@example.com',
  customer_name: 'Jane Doe',
  products: [
    { code: 'monthly-plan', name: 'Monthly Plan', price: 29.99, quantity: 1, type: 'main' }
  ],
  amount: 29.99,
  currency_code: 'USD',
  tax_amount: 0,
  shipping_amount: 0,
  discount_amount: 0,
  frequency: 1,
  frequency_unit: 'month',               // day | week | month | year
  next_charge_at: '2026-05-12T00:00:00Z',
  started_at: '2026-04-12T00:00:00Z',
  paused_at: null,
  resume_at: null,
  canceled_at: null,
  cancel_reason: null,
  cycle_number: 2,
  trial_days: 0,
  first_charge_free: false,
  original_transaction_id: 'txn_xyz789',
  gateway: 'stripe',
  card_last4: '4242',
  card_brand: 'visa',
  created_at: '2026-04-12T00:00:00Z',
  updated_at: '2026-05-01T00:00:00Z'
}
```

### `getSubscription(arg)`

Fetch a single subscription. Accepts either a **transaction ID string** or a **filter object**.

**String form** — fetch by original transaction ID (existing behavior):

```javascript theme={null}
var sub = getSubscription(request.query.id);
if (sub) {
  setVariable('subscription', sub);
}
```

**Object form** — fetch the first matching subscription from the per-request cache:

| Property | Type | Default | Description |
| - | - | - | - |
| `code` | string | — | Filter by product code in the subscription's `products` array. |
| `status` | string | `'active'` | Filter by status. Use `'any'` to skip status filtering. |

```javascript theme={null}
// First active subscription for a specific product
var sub = getSubscription({ code: 'monthly-plan' });

// Most recent canceled subscription (win-back flow)
var canceled = getSubscription({ code: 'monthly-plan', status: 'canceled' });
if (canceled) {
  setVariable('canceled_at', canceled.canceled_at);
  setVariable('show_winback', true);
}

// First subscription regardless of code, any status
var any = getSubscription({ status: 'any' });
```

### `hasSubscription(filter?)`

Returns `true` if the customer has at least one subscription matching the filter, `false` otherwise. All fields are optional.

| Property | Type | Default | Description |
| - | - | - | - |
| `code` | string | — | Match by product code. |
| `status` | string | `'active'` | Match by status. Use `'any'` to skip. |
| `date` | string | — | ISO date string. When set, ignores `status` and instead checks whether the subscription was active on that date (`started_at ≤ date` and `canceled_at` is null or after the date). |

```javascript theme={null}
// Does the customer have any active subscription?
var isSubscribed = hasSubscription();

// Active subscription for a specific product (content gate)
if (hasSubscription({ code: 'premium-plan' })) {
  setVariable('show_premium', true);
}

// Was the customer subscribed on a specific date? (date-based gate)
if (hasSubscription({ code: 'premium-plan', date: '2026-01-01' })) {
  setVariable('can_view_jan_content', true);
}

// Does the customer have a past-due subscription? (dunning banner)
if (hasSubscription({ status: 'past_due' })) {
  setVariable('show_billing_warning', true);
}
```

### `countSubscriptions(filter?)`

Returns the number of subscriptions matching the filter. Same filter shape as `hasSubscription`, excluding `date`.

| Property | Type | Default | Description |
| - | - | - | - |
| `code` | string | — | Filter by product code. |
| `status` | string | `'active'` | Filter by status. Use `'any'` for all statuses. |

```javascript theme={null}
var activeCount = countSubscriptions();
setVariable('active_sub_count', activeCount);

var totalCount = countSubscriptions({ status: 'any' });
var canceledCount = countSubscriptions({ status: 'canceled' });
```

### `cancelSubscription(transactionId, reason?)`

Cancel an active or paused subscription. Fires the `subscription_cancel` event.

```javascript theme={null}
var result = cancelSubscription('txn_xyz789', 'Too expensive');
if (!result.ok) {
  setVariable('error_message', result.error);
}
```

### `pauseSubscription(transactionId, resumeAt?)`

Pause an `active` subscription. Optional `resumeAt` is an ISO date string for an automatic resume — invalid dates return `{ ok: false, error: 'Invalid resume_at date' }`.

```javascript theme={null}
pauseSubscription('txn_xyz789');
pauseSubscription('txn_xyz789', '2026-08-01T00:00:00Z');
```

### `resumeSubscription(transactionId)`

Resume a `paused` subscription. If the stored `next_charge_at` is in the past, it is automatically advanced based on the subscription's frequency.

```javascript theme={null}
resumeSubscription('txn_xyz789');
```

### `skipSubscription(transactionId)`

Skip the next billing cycle on an `active` subscription. Returns the new next charge date on success.

```javascript theme={null}
var result = skipSubscription('txn_xyz789');
if (result.ok) {
  setVariable('next_charge', result.next_charge_at);
}
```

### `changeSubscriptionFrequency(transactionId, interval, intervalCount)`

Change the billing cadence on an `active` or `paused` subscription. `interval` must be one of `day`, `week`, `month`, `year`. `intervalCount` must be a positive integer.

```javascript theme={null}
var result = changeSubscriptionFrequency('txn_xyz789', 'month', 2);
// → { ok: true, frequency_unit: 'month', frequency: 2, next_charge_at: '2026-06-12T...' }
```

## Conversions

### `getConversions(email)`

Look up conversions (purchases) by email address.

```javascript theme={null}
var conversions = getConversions('john@example.com');

if (conversions.length > 0) {
  setVariable('returning_customer', true);
}
```

Returns an array of conversion records with fields like `public_order_id`, `created_at`, `customer_email`, `product_name`, `total`, `currency_code`, `status`.

## Products

### `getProduct(code)`

Fetch a single product by its product code.

```javascript theme={null}
var product = getProduct('premium-plan');

if (product) {
  setVariable('product_name', product.name);
  setVariable('product_price', product.price);
}
```

### `resolveVariant(product, code?)`

Pick which variant a page should start on. Returns `null` for a product with no
variants, so you can branch on it.

```javascript theme={null}
var product = getProduct('menosoothe');
var picked  = resolveVariant(product, request.route_params.code);

if (picked) {
  setVariable('price', picked.price);
  setVariable('buy_code', picked.code);   // what add-to-cart submits
}
```

`code` may be a **variant code** or the **linked product's code**, so a URL like
`/shop/product/menosoothe-3` resolves without you mapping it yourself. With no match,
or no code, the product's default variant is returned.

### Variants on a product

Every product returned by `getProduct`/`getProducts` carries a normalised `variants`
array, ordered by position, plus `product_fields` (the option axes) and `has_variants`.

```javascript theme={null}
var product = getProduct('menosoothe');

@foreach(v in product.variants)
  {{ v.title }}          // "3 Bottles"  - joined option values
  {{ v.code }}           // "menosoothe-3" - resolved through the linked product
  {{ v.price }}          // 177
  {{ v.retail_price }}   // 297
  {{ v.per_unit_price }} // 59  - price / units, precomputed
  {{ v.on_sale }}        // true when retail_price > price
  {{ v.is_default }}     // exactly one variant is true
@endforeach
```

| Field | Notes |
| - | - |
| `code` | Variant code, else the linked product's code, else the variant id. This is what you submit to the cart. |
| `linked_product_id` / `linked_product_code` | The product this variant resolves to. `null` for a standalone variant. |
| `title` | Option values joined with `/`, or `Default` when the product has no option axes. |
| `option_values` | Object keyed by option name, e.g. `{ "Pack size": "3 Bottles" }`. |
| `per_unit_price` | `price / units`, or `null` when `units` is unset. |
| `on_sale` | `true` when `retail_price` is greater than `price`. |
| `position` | Display order. The array is already sorted by it. |
| `is_default` | Exactly one variant per product is `true`. |

<Note>
  Commercial fields resolve through the linked product (see
  [Product Variants](/products/variants)), so `price`, `sku` and `image` are already the
  values you should show — no second lookup needed.
</Note>

### `getProducts(filters?)`

Fetch products with optional filters.

```javascript theme={null}
// All products
var all = getProducts();

// Filtered
var physical = getProducts({ type: 'physical' });
var subscriptions = getProducts({ classification: 'subscription' });
var specific = getProducts({ codes: 'plan-a,plan-b,plan-c' });
```

| Filter | Type | Description |
| - | - | - |
| `type` | string | `'physical'`, `'digital'`, or `'any'` |
| `classification` | string | `'subscription'`, `'one-time'`, or `'any'` |
| `codes` | string | Comma-separated product codes |

### `getAllProducts()`

Fetch all products for the brand (no filtering).

```javascript theme={null}
var products = getAllProducts();
console.log('Total products:', products.length);
```

### `getProductByCode(merchantCode, productCode)`

Look up a product by merchant gateway code and the merchant-specific product code.

```javascript theme={null}
var product = getProductByCode('stripe', 'price_1234');
```

### Product files and download URLs

Catalog products can include attached downloads. **`getProduct`**, **`getAllProducts`**, **`getProductByCode`**, and **`getProducts`** (with **or without** filters) all return the same normalized shape, so you can rely on the same fields in every code path.

Use these fields:

| Field | Type | Description |
| - | - | - |
| **`product_files`** | array | All file rows attached to the product (always an array — never a JSON string). Each item: `{ id, purpose, title, description, image, file, sort_order, is_primary, metadata }`. `purpose` is `'digital'` or `'bonus'` (defaults to `'digital'` when missing). Rows with no `file` URL are filtered out. |
| **`digital_files`** | array | Subset of `product_files` where `purpose === 'digital'`. Same row shape. |
| **`bonus_files`** | array | Subset of `product_files` where `purpose === 'bonus'`. Same row shape. |
| **`digital_file`** | string | URL of the **primary** digital file (the `is_primary` row with the lowest `sort_order` whose `purpose` is `'digital'`). Falls back to the legacy `digital_file` column on the product if set. Empty string when none. |
| **`bonus_file`** | string | URL of the **primary** bonus file (the `is_primary` row with the lowest `sort_order` whose `purpose` is `'bonus'`). Falls back to the legacy `bonus_file` column, then to any primary file. Empty string when none. |
| **`primary_download_url`** | string | URL of the overall primary file across all purposes (`is_primary DESC`, then `sort_order ASC`). Empty string when none. |

Inside each `product_files` row:

| Field | Type | Description |
| - | - | - |
| `id` | number \| null | Internal file id. |
| `purpose` | string | `'digital'` or `'bonus'`. |
| `title` | string | Display title. |
| `description` | string | Optional description. |
| `image` | string | Optional preview image URL. |
| `file` | string | Download URL. Always present (rows without a URL are dropped). |
| `kind` | string | Coarse classification derived from `metadata.extension` and `metadata.mime_type`. One of `'audio'`, `'video'`, `'document'`, `'image'`, `'archive'`, `'file'`. Use this to branch on file type without re-parsing the URL. |
| `sort_order` | number | Display / primary-selection order (defaults to position in the array if not stored). |
| `is_primary` | boolean | Whether this row is the primary file for its purpose. |
| `metadata` | object | Public metadata object (always an object, parsed from JSON when stored that way). See **Metadata fields** below. Internal storage pointers are intentionally not exposed. |

#### Metadata fields

The `metadata` object on each `product_files` row only exposes the following fields:

| Field | Type | Description |
| - | - | - |
| `mime_type` | string \| null | MIME type of the file (e.g. `'audio/mpeg'`, `'application/pdf'`). |
| `size` | number \| null | Size in bytes. |
| `checksum` | string \| null | Optional checksum, when one was recorded at upload. |
| `extension` | string | Lowercase extension without the dot (e.g. `'mp3'`, `'pdf'`, `'docx'`). Derived from the `file` URL when possible, with a small mime-type fallback for opaque/signed URLs. Empty string when neither source can produce one. |

<Tip>
  Internal storage pointers (`provider`, `storage_path`, `brand_file_id`) used to be present on this object and are now intentionally hidden — they were only useful to the platform itself and should not be relied on by scripts or templates.
</Tip>

**Example** — pick the primary bonus URL with a safe fallback, then list all digital files with their type:

```javascript theme={null}
var p = getProduct('my-sku');

if (p && (p.bonus_file || p.primary_download_url)) {
  setVariable('bonus_href', p.bonus_file || p.primary_download_url);
}

if (p && p.digital_files && p.digital_files.length) {
  for (var i = 0; i < p.digital_files.length; i++) {
    var row = p.digital_files[i];
    console.log(
      row.title,
      row.file,
      'kind:', row.kind,
      'ext:', row.metadata && row.metadata.extension,
      'mime:', row.metadata && row.metadata.mime_type
    );
  }
}
```

**Example** — list every bonus across a filtered product set:

```javascript theme={null}
var bonuses = getProducts({ classification: 'bonus' });

for (var i = 0; i < bonuses.length; i++) {
  var b = bonuses[i];
  console.log(b.title, '→', b.bonus_file || b.primary_download_url);
}
```

The same functions are available in **backend** page templates under the same names (`getProduct` / `getProducts` / `getAllProducts`), see [Products, categories & shipping (backend)](/backend-template-engine/products-and-shipping).

### `productDownloads(product)`

Roll up everything a member-area UI normally needs to render "what can the customer actually download for this product" into a single flat array. Replaces the recurring `extractFiles` / "classify by extension" gymnastics — every entry already carries `kind`, so you can `switch` on it without parsing URLs.

Source order, deduplicated by URL (first occurrence wins):

1. `digital_files` (purpose=`'digital'`)
2. `bonus_files` (purpose=`'bonus'`)
3. anything left in `product_files` not already picked up
4. legacy scalar `digital_file` / `bonus_file` columns — surfaced **only when no file rows exist**, so you never get duplicates of a row that's already in `product_files`

Each entry:

| Field | Type | Description |
| - | - | - |
| `url` | string | Download URL (always present). |
| `title` | string | Display title. Falls back to `'Download'`. |
| `kind` | string | One of `'audio'`, `'video'`, `'document'`, `'image'`, `'archive'`, `'file'`. |
| `purpose` | string | `'digital'` or `'bonus'`. |
| `extension` | string | Lowercase extension without the dot (e.g. `'mp3'`). |
| `mime_type` | string \| null | MIME type when known. |
| `size` | number \| null | Size in bytes when known. |
| `is_primary` | boolean | Whether this row is the primary file for its purpose. |
| `sort_order` | number | Display order. |

**Example** — render a member's library entry without any classify-by-URL logic:

```javascript theme={null}
var p = getProduct('my-sku');
var files = productDownloads(p);

for (var i = 0; i < files.length; i++) {
  var f = files[i];
  switch (f.kind) {
    case 'audio':    console.log('🎧', f.title, f.url); break;
    case 'video':    console.log('🎬', f.title, f.url); break;
    case 'document': console.log('📄', f.title, f.url); break;
    case 'image':    console.log('🖼️', f.title, f.url); break;
    case 'archive':  console.log('📦', f.title, f.url); break;
    default:         console.log('📁', f.title, f.url);
  }
}
```

The same helper is available in backend page templates under the same name, see [Products, categories & shipping (backend)](/backend-template-engine/products-and-shipping).

### `productSavings(product)`

Compute savings info from a product's `price` and `retail_price`. Returns an object:

```javascript theme={null}
var product = getProduct('premium-plan');
var savings = productSavings(product);

// savings = {
//   amount: 20,
//   percent: 25,
//   amountFormatted: '$20.00',
//   percentFormatted: '25%'
// }

if (savings.percent > 0) {
  setVariable('discount_badge', 'Save ' + savings.percentFormatted);
}
```

Returns `{ amount: 0, percent: 0, amountFormatted: '', percentFormatted: '' }` when there is no discount.

### `subscriptionSummary(product)`

Returns a human-readable subscription description string.

```javascript theme={null}
var product = getProduct('monthly-plan');
var label = subscriptionSummary(product);
// e.g. "7-day free trial · Every 1 month"

setVariable('subscription_label', label);
```

Returns an empty string for non-subscription products.

### `formatPrice(value, currency?)`

Format a numeric price with the given currency code.

```javascript theme={null}
var formatted = formatPrice(49.99, 'USD');
// "$49.99"
setVariable('display_price', formatted);
```

## Courses

### `getCourse(courseId)`

Fetch a course by ID, including modules and contents.

```javascript theme={null}
var course = getCourse(42);
if (course) {
  setVariable('course_title', course.title);
  setVariable('lesson_count', course.total_lesson_count);
}
```

### `getCourseBySlug(slug)`

Fetch a course by its URL slug.

```javascript theme={null}
var course = getCourseBySlug('javascript-basics');
```

### `getModuleBySlug(courseSlug, moduleSlug)`

Fetch a single module with its contents.

```javascript theme={null}
var module = getModuleBySlug('javascript-basics', 'variables');
if (module) {
  setVariable('module_title', module.title);
}
```

### `getCourses()`

Fetch all courses for the brand with lesson and module counts.

```javascript theme={null}
var courses = getCourses();
setVariable('course_count', courses.length);
```

### `getCoursesByCategorySlug(categorySlug)`

Filter courses by category slug.

```javascript theme={null}
var marketingCourses = getCoursesByCategorySlug('marketing');
setVariable('marketing_course_count', marketingCourses.length);
```

### `getCategoriesWithCourses()`

Get all course categories with their courses grouped together.

```javascript theme={null}
var categories = getCategoriesWithCourses();
// [
//   { category_slug: 'marketing', category_name: 'Marketing', courses: [...] },
//   { category_slug: 'design', category_name: 'Design', courses: [...] },
// ]

setVariable('category_count', categories.length);
```

### `getCourseForCustomer(slug)`

Fetch a single course with enrollment data for the current customer. Returns the full module/lesson tree plus `completed_content_ids`, `progress_percent`, `is_assigned`, and `started`.

```javascript theme={null}
var course = getCourseForCustomer('javascript-basics');
if (course && course.is_assigned) {
  setVariable('progress', course.progress_percent);
}
```

### `getCoursesForCustomer()`

Fetch all courses the current customer is enrolled in. Same as `getCourses(true)`.

```javascript theme={null}
var myCourses = getCoursesForCustomer();
```

Each course includes `module_count`, `lesson_count`, `progress_percent`, `completed_content_ids`, and `is_assigned`.

### `getCoursesForCustomerByCategorySlug(categorySlug)`

Fetch the current customer's enrolled courses, filtered by category slug. Returns an empty array if the category has no enrolled courses.

```javascript theme={null}
var marketing = getCoursesForCustomerByCategorySlug('marketing');
setVariable('marketing_courses', marketing);
```

### `getCategoriesWithCoursesForCustomer()`

Get all course categories that contain at least one course the current customer is enrolled in, with the enrolled courses grouped per category. Useful for category-tab navigation on a member-facing courses page.

```javascript theme={null}
var categories = getCategoriesWithCoursesForCustomer();
// [
//   { category_slug: 'marketing', category_name: 'Marketing', courses: [...] },
//   { category_slug: 'design',    category_name: 'Design',    courses: [...] }
// ]
```

### `getCompletedLessonsCount(opts?)`

Count completed lessons across all enrolled courses, or for a specific course.

```javascript theme={null}
var totalDone = getCompletedLessonsCount();
var courseDone = getCompletedLessonsCount({ course: 'javascript-basics' });
```

### `getCourseProgress(opts?)`

Get a structured progress summary with per-course and overall completed/total lesson counts.

```javascript theme={null}
var progress = getCourseProgress();
// progress.completedLessons  → 12
// progress.totalLessons      → 48
// progress.courses → [{ slug, title, completedLessons, totalLessons, progressPercent }]
```

## Blog

### `getBlog(blogId?)`

Fetch a blog by ID. If no ID is provided, returns the default blog for the current domain.

```javascript theme={null}
var blog = getBlog();
if (blog) {
  setVariable('blog_name', blog.name);
}

// Or by specific ID
var specific = getBlog(5);
```

### `getBlogArticles(blogId, page?, perPage?)`

Fetch published blog articles with pagination.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `blogId` | number | — | Blog ID (required) |
| `page` | number | `1` | Page number |
| `perPage` | number | `12` | Articles per page (max 100) |

```javascript theme={null}
var blog = getBlog();
if (blog) {
  var articles = getBlogArticles(blog.id, 1, 10);
  setVariable('article_count', articles.length);
  setVariable('articles', articles);
}
```

Each article includes a `body` field with the article content.

### `getBlogArticle(blogId, slug)`

Fetch a single published article by blog ID and slug.

```javascript theme={null}
var article = getBlogArticle(1, 'getting-started');
if (article) {
  setVariable('article_title', article.title);
  setVariable('article_body', article.body);
}
```

### `getBlogCategories(blogId)`

Get category summaries for a blog's published articles.

```javascript theme={null}
var categories = getBlogCategories(1);
setVariable('blog_categories', categories);
```

### `getRelatedArticles(blogId, articleId, limit?)`

Fetch related articles for a given article.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `blogId` | number | — | Blog ID |
| `articleId` | number | — | Article to find related content for |
| `limit` | number | `4` | Max related articles (1–24) |

```javascript theme={null}
var related = getRelatedArticles(1, 42, 3);
setVariable('related_articles', related);
```

## Purchase Links

These functions generate URLs for the payment flow. They are synchronous.

### `buy(productCode)`

Generate a purchase link for a product.

```javascript theme={null}
var link = buy('premium-plan');
setVariable('buy_url', link);
```

### `upsell(productCode)`

Generate an upsell link (one-click purchase for existing customers).

```javascript theme={null}
var link = upsell('vip-addon');
setVariable('upsell_url', link);
```

### `downsell(productCode)`

Generate a downsell link (same mechanics as upsell).

```javascript theme={null}
var link = downsell('basic-addon');
setVariable('downsell_url', link);
```

### `decline(productCode)`

Generate a decline link (skip the upsell offer and proceed).

```javascript theme={null}
var link = decline('vip-addon');
setVariable('decline_url', link);
```

### `upsellUpgrade(oldSku, newSku)`

Generate a subscription upgrade link. Produces a JavaScript action URL that calls the server API to change the customer's subscription product. See [Subscription Upsells](/products/subscription-upsells).

```javascript theme={null}
var link = upsellUpgrade('monthly_basic', 'monthly_premium');
setVariable('upgrade_url', link);
```

### `upsellCancel()`

Generate a subscription cancellation link. Produces a JavaScript action URL that calls the server API to cancel the customer's subscription.

```javascript theme={null}
var link = upsellCancel();
setVariable('cancel_url', link);
```

## Assets

### `asset(path)`

Generate a full CDN URL for a brand asset.

```javascript theme={null}
var cssUrl = asset('/main.css');
var imgUrl = asset('/images/hero.jpg');

setVariable('css_url', cssUrl);
```

Automatically appends a cache-busting parameter when `?nc`, `?no_cache`, or `?preview_key` is present in the request.

## Visitor Control

### `whitelistVisitor()`

Whitelist the current visitor by setting an encrypted cookie. Whitelisted visitors bypass access restrictions.

```javascript theme={null}
var customer = getCustomer();
if (customer.email === 'admin@example.com') {
  whitelistVisitor();
}
```

### `blacklistVisitor()`

Blacklist the current visitor by setting an encrypted cookie.

```javascript theme={null}
if (request.query.block === 'true') {
  blacklistVisitor();
  redirect('/blocked');
}
```

## Session Items

These functions read and write custom session items that are **compatible with the template engine's `setSessionItem` / `getSessionItem`** functions. Values are stored with a `custom_` prefix and base64-encoded.

Use these when you need to share data between backend scripts and template-engine expressions on the same page or across pages within the same session.

### `setSessionItem(key, value)`

Store a custom value in the session. Keys are sanitized to `[a-zA-Z0-9_]`. Values over 64KB are silently dropped. Pass `null` to delete.

```javascript theme={null}
setSessionItem('preferred_plan', 'premium');
setSessionItem('quiz_score', '85');
```

### `getSessionItem(key)`

Retrieve a custom session item. Returns an empty string if not found.

```javascript theme={null}
var plan = getSessionItem('preferred_plan');
if (plan === 'premium') {
  setVariable('show_premium_banner', true);
}
```

### `clearSessionItem(key)`

Remove a custom session item.

```javascript theme={null}
clearSessionItem('preferred_plan');
```

<Note>
  For raw session access (without the `custom_` prefix and base64 encoding), use `session.get(key)` and `session.set(key, value)` from the [Actions](/backend-scripts/actions) page.
</Note>

## CRM Data

<Note>
  **Entries vs. Fields**: An **entry** is a single record or document stored in the CRM (like a row in a database, representing e.g. a specific check-in for a customer). A **field** (`fieldKey`) is a specific piece of data that lives inside an entry (like a column, e.g. "current\_weight").
</Note>

CRM entries are stored per brand. Every read/write is scoped by:

* **`brand_id`** — from the session (always applied server-side)
* **`slug`** — the CRM **entity** machine name from entity settings (e.g. `weight-tracker`), **required** on every call. This is **not** the same as `referenceType` (`customer`, `order`, …).
* **`reference_type` + `reference_id`** — which record the entry is attached to. Defaults: `referenceType` → `'customer'`, `referenceId` → current session **`customer_id`** when omitted or `null`.

Pass a **single options object** only (positional arguments are not supported). Missing `slug` or other required keys throws `TypeError`. Unknown `slug` for the brand also throws. Invalid field values still return `false` / `null` / `[]` after sanitization where applicable.

Slug aliases: `crmEntitySlug`, `crm_entity_slug`. Reference aliases: `reference_type`, `reference_id`. Field key: `fieldKey` or `field_key`.

Write functions (`setCrmField`, `setCrmFields`, `addCrmFieldValue`, `clearCrmEntries`) accept an optional **`async`** parameter (default `false`). When `true`, the write runs in the background — faster but with eventual consistency. Read functions are always synchronous.

```javascript theme={null}
getCrmField({ slug: 'weight-tracker', fieldKey: 'current_weight' });

getCrmFields({ slug: 'weight-tracker', fieldKeys: ['current_weight', 'goal_weight'] });

setCrmField({ slug: 'weight-tracker', fieldKey: 'current_weight', value: 182, force: true });

setCrmFields({
  slug: 'weight-tracker',
  fields: [
    { fieldKey: 'current_weight', value: 182 },
    { fieldKey: 'goal_weight', value: 165 }
  ]
});

// Another record type / id
setCrmField({ slug: 'weight-tracker', referenceType: 'order', referenceId: '12345', fieldKey: 'status', value: 'shipped' });
```

### `ensureCrmEntity({ slug, name?, fields?, ... })`

Idempotently provisions a CRM entity (and optionally seeds its field schema). Safe to call on every page render — existing entities and fields are never overwritten, only missing keys are inserted.

Use this at the top of a backend script in templates that ship to many brands so the CRM entity is auto-created on first use, without requiring an admin to pre-configure it.

| Property | Type | Default | Description |
| - | - | - | - |
| `slug` | string | **required** | Machine name for the entity (e.g. `member-settings`). Must match `^[a-z0-9][a-z0-9_-]*$`. |
| `name` | string | slug | Human-readable entity name shown in the admin UI. |
| `singularName` | string | `null` | Singular label (e.g. "Member Setting"). Alias: `singular_name`. |
| `pluralName` | string | `null` | Plural label (e.g. "Member Settings"). Alias: `plural_name`. |
| `icon` | string | `null` | Icon name (Lucide icon, admin UI). |
| `color` | string | `null` | Accent color (CSS color string). |
| `fields` | array | `[]` | Optional field schema. Each item: `{ key, label?, type?, options?, validation_rules?, visible_to_team_ids? }`. |

Field `type` values: `text`, `textarea`, `email`, `tel`, `url`, `number`, `integer`, `decimal`, `currency`, `date`, `datetime`, `time`, `select`, `multiselect`, `checkbox`, `boolean`, `radio`, `json`, `rich_text`, `wysiwyg` (rich text fields: values are HTML strings). For `select`/`multiselect`/`radio` pass `options: ['a','b']` or `[{ value: 'a', label: 'A' }]`.

Returns:

```javascript theme={null}
{
  id: 42,
  slug: 'member-settings',
  created: true,        // false if entity already existed
  fields_added: 3,      // newly inserted fields
  fields_skipped: 2     // already existed (left untouched)
}
```

Example:

```javascript theme={null}
ensureCrmEntity({
  slug: 'member-settings',
  name: 'Member Settings',
  icon: 'settings',
  fields: [
    { key: 'preferred_name', label: 'Preferred name', type: 'text' },
    { key: 'time_zone',      label: 'Time zone',      type: 'select',
      options: ['UTC', 'Europe/London', 'America/New_York'] },
    { key: 'marketing_opt_in', label: 'Marketing opt-in', type: 'checkbox' },
  ],
});

// Now safe to read/write — the entity definitely exists.
var name = getCrmField({ slug: 'member-settings', fieldKey: 'preferred_name' });
```

**Limits**: max 5 `ensureCrmEntity` calls per page execution. Exceeding the limit returns `{ id: null, created: false, error: 'rate_limited' }`.

### `getCrmEntries({ slug, referenceType?, referenceId?, limit? })`

Fetch CRM entries for one entity slug and one reference.

| Property | Type | Default | Description |
| - | - | - | - |
| `slug` | string | **required** | CRM entity slug from entity settings |
| `referenceType` | string | `'customer'` | Linked record type |
| `referenceId` | string | session `customer_id` | Linked record id |
| `limit` | number | `50` | Max entries (max 200) |

```javascript theme={null}
var entries = getCrmEntries({ slug: 'weight-tracker', limit: 50 });

for (var i = 0; i < entries.length; i++) {
  console.log(entries[i].title, entries[i].values_flat);
}
```

Each entry object contains:

```javascript theme={null}
{
  id: 'abc123',
  reference_type: 'customer',
  reference_id: 'xyz789',
  values_flat: {
    current_weight: 182,
    goal_weight: 165,
    last_checkin: '2026-03-15'
  },
  created_at: '2026-03-15T10:00:00Z',
  updated_at: '2026-03-20T14:30:00Z'
}
```

### `getCrmField({ slug, fieldKey, referenceType?, referenceId? })`

Reads one field from the first matching entry for that **slug** + reference.

| Property | Type | Default | Description |
| - | - | - | - |
| `slug` | string | **required** | CRM entity slug |
| `fieldKey` | string | **required** | Field key (e.g. `current_weight`, `goal_weight`) |
| `referenceType` | string | `'customer'` | Linked record type |
| `referenceId` | string | session `customer_id` | Linked record id |

```javascript theme={null}
var weight = getCrmField({ slug: 'weight-tracker', fieldKey: 'current_weight' });

if (weight && Number(weight) <= 165) {
  setVariable('show_goal_reached', true);
}
```

### `getCrmFields({ slug, fieldKeys, referenceType?, referenceId? })`

Reads multiple fields from the first matching entries for that **slug** + reference. Returns an object mapping `fieldKey` -> `value`.

| Property | Type | Default | Description |
| - | - | - | - |
| `slug` | string | **required** | CRM entity slug |
| `fieldKeys` | array | **required** | Array of field keys (e.g. `['current_weight', 'goal_weight']`) |
| `referenceType` | string | `'customer'` | Linked record type |
| `referenceId` | string | session `customer_id` | Linked record id |

```javascript theme={null}
var fields = getCrmFields({ slug: 'weight-tracker', fieldKeys: ['current_weight', 'goal_weight'] });

if (fields.current_weight && Number(fields.current_weight) <= 165) {
  setVariable('show_goal_reached', true);
}
```

### `setCrmField({ slug, fieldKey, value, force?, referenceType?, referenceId?, async? })`

Updates an existing entry's field or creates a new entry under that entity slug and reference.

| Property | Type | Default | Description |
| - | - | - | - |
| `slug` | string | **required** | CRM entity slug |
| `fieldKey` | string | **required** | Field key to set |
| `value` | any | **required** | Must be present (`value: 0` / `false` allowed) |
| `force` | boolean | `false` | Skip per-key entry scan — merge into the newest entry directly |
| `referenceType` | string | `'customer'` | Linked record type |
| `referenceId` | string | session `customer_id` | Linked record id |
| `async` | boolean | `false` | When `true`, write runs in background (faster, eventual consistency) |

```javascript theme={null}
setCrmField({ slug: 'weight-tracker', fieldKey: 'current_weight', value: 182 });
setCrmField({ slug: 'weight-tracker', fieldKey: 'last_checkin', value: new Date().toISOString() });
```

**Performance tip:** When setting multiple fields in one script, pass `force: true`. Without it, each call searches all entries (up to 100) to find the document containing that key. With `force`, it fetches only the newest entry (limit 1) and merges the field into it — much faster for sequential writes:

```javascript theme={null}
setCrmField({ slug: 'weight-tracker', fieldKey: 'current_weight', value: 182, force: true });
setCrmField({ slug: 'weight-tracker', fieldKey: 'goal_weight', value: 165, force: true });
setCrmField({ slug: 'weight-tracker', fieldKey: 'last_checkin', value: today, force: true });
```

### `setCrmFields({ slug, fields, force?, referenceType?, referenceId?, async? })`

Sets multiple field values for the same CRM entity + reference in one read/write cycle. This is the preferred API when one script needs to write several fields at once.

| Property | Type | Default | Description |
| - | - | - | - |
| `slug` | string | **required** | CRM entity slug |
| `fields` | array | **required** | Non-empty array of `{ fieldKey, value }` objects |
| `force` | boolean | `false` | Skip per-key scan and merge into the newest entry directly |
| `referenceType` | string | `'customer'` | Linked record type |
| `referenceId` | string | session `customer_id` | Linked record id |
| `async` | boolean | `false` | When `true`, write runs in background |

```javascript theme={null}
setCrmFields({
  slug: 'weight-tracker',
  fields: [
    { fieldKey: 'current_weight', value: 182 },
    { fieldKey: 'goal_weight', value: 165 },
    { fieldKey: 'last_checkin', value: today }
  ]
});
```

Snake\_case keys are also accepted inside `fields`:

```javascript theme={null}
setCrmFields({
  slug: 'affiliate-requests',
  referenceType: 'affiliate_request',
  referenceId: 'leon@elasticfunnels.io',
  fields: [
    { field_key: 'affiliate_experience', value: 'Wellness' },
    { field_key: 'niche', value: 'Health' }
  ]
});
```

Behavior matches `setCrmField`:

* If an existing entry for the same reference already contains one of the requested keys, that entry is updated.
* If the keys are new but the reference already has entries, the newest entry is reused.
* A new CRM entry is created only when that reference has no entry yet.

### `addCrmFieldValue({ slug, fieldKey, value, referenceType?, referenceId?, async? })`

Creates a **new** CRM entry with the given field value. Unlike `setCrmField` which upserts a single value per key, this always creates a new entry — enabling multiple values for the same key over time.

| Property | Type | Default | Description |
| - | - | - | - |
| `slug` | string | **required** | CRM entity slug |
| `fieldKey` | string | **required** | Field key to store the value under |
| `value` | any | **required** | The value to store (string, number, boolean, or object) |
| `referenceType` | string | `'customer'` | Linked record type |
| `referenceId` | string | session `customer_id` | Linked record id |
| `async` | boolean | `false` | When `true`, write runs in background |

```javascript theme={null}
addCrmFieldValue({
  slug: 'weight-tracker',
  fieldKey: 'weighin_history',
  value: { date: today, weight: 182, notes: 'post-workout' }
});
```

### `getCrmFieldValues({ slug, fieldKey, limit?, referenceType?, referenceId? })`

Collects all values for a given field key across CRM entries. Returns an array of the raw values (string, number, object, etc.), newest first.

| Property | Type | Default | Description |
| - | - | - | - |
| `slug` | string | **required** | CRM entity slug |
| `fieldKey` | string | **required** | Field key to collect values for |
| `limit` | number | `50` | Max values to return (max 200) |
| `referenceType` | string | `'customer'` | Linked record type |
| `referenceId` | string | session `customer_id` | Linked record id |

```javascript theme={null}
var history = getCrmFieldValues({ slug: 'weight-tracker', fieldKey: 'weighin_history', limit: 10 });

for (var i = 0; i < history.length; i++) {
  console.log(history[i].date, history[i].weight);
}
```

### `clearCrmEntries({ slug, referenceType?, referenceId?, async? })`

Deletes **all** CRM entries for the given entity slug and reference. Returns `{ ok: boolean, deleted: number }`.

| Property | Type | Default | Description |
| - | - | - | - |
| `slug` | string | **required** | CRM entity slug |
| `referenceType` | string | `'customer'` | Linked record type |
| `referenceId` | string | session `customer_id` | Linked record id |
| `async` | boolean | `false` | When `true`, deletes run in background |

```javascript theme={null}
var result = clearCrmEntries({ slug: 'weight-tracker' });
console.log(result.deleted, 'entries removed');
```

### `moveCrmLead({ slug, pipelineId?, pipelineSlug?, stageId?, stageSlug?, referenceType?, referenceId?, allEntries?, async? })`

Moves a CRM entry to a specific pipeline and stage. Either `pipelineId` or `pipelineSlug` is required; either `stageId` or `stageSlug` is required.

| Property | Type | Default | Description |
| - | - | - | - |
| `slug` | string | **required** | CRM entity slug |
| `pipelineId` | number | — | Pipeline id (or use `pipelineSlug`) |
| `pipelineSlug` | string | — | Pipeline slug (or use `pipelineId`) |
| `stageId` | number | — | Stage id (or use `stageSlug`) |
| `stageSlug` | string | — | Stage slug (or use `stageId`) |
| `referenceType` | string | `'customer'` | Linked record type |
| `referenceId` | string | session `customer_id` | Linked record id |
| `allEntries` | boolean | `false` | When `true`, updates all matching entries (not just the newest) |
| `async` | boolean | `false` | When `true`, update runs in background |

Returns `{ ok, moved, totalMatched, pipeline_id, stage_id }` on success, or `{ ok: false, moved: 0, error }`.

```javascript theme={null}
var result = moveCrmLead({ slug: 'deals', pipelineSlug: 'sales', stageSlug: 'qualified' });

if (!result.ok) {
  console.log('Move failed:', result.error);
}
```

### `moveCrmToStage({ slug, stageId?, stageSlug?, pipelineId?, pipelineSlug?, referenceType?, referenceId?, allEntries?, async? })`

Moves a CRM entry to a specific stage. The pipeline is resolved from the stage automatically — only `stageId` or `stageSlug` is strictly required (pipeline id/slug can narrow the lookup if stage slugs are not unique across pipelines).

```javascript theme={null}
moveCrmToStage({ slug: 'deals', stageSlug: 'won' });
```

### `moveCrmToPipeline({ slug, pipelineId?, pipelineSlug?, stageId?, stageSlug?, referenceType?, referenceId?, allEntries?, async? })`

Moves a CRM entry into a pipeline. The entry lands on the pipeline's first stage unless a specific stage is provided.

```javascript theme={null}
moveCrmToPipeline({ slug: 'deals', pipelineSlug: 'onboarding' });
```

### `moveCrmToEntity({ fromSlug, toSlug, fieldMap, referenceType?, referenceId?, pipelineId?, pipelineSlug?, stageId?, stageSlug?, removeFromOld?, async? })`

Copies field values from one CRM entity to another for the same reference. Use this to promote a lead to a deal, or migrate data between entity types.

| Property | Type | Default | Description |
| - | - | - | - |
| `fromSlug` | string | **required** | Source entity slug |
| `toSlug` | string | **required** | Target entity slug (must differ from `fromSlug`) |
| `fieldMap` | object | **required** | `{ sourceFieldKey: targetFieldKey }` mapping — at least one pair required |
| `referenceType` | string | `'customer'` | Linked record type |
| `referenceId` | string | session `customer_id` | Linked record id |
| `pipelineId` / `pipelineSlug` | number / string | — | Optional pipeline to place the new entry in |
| `stageId` / `stageSlug` | number / string | — | Optional stage within that pipeline |
| `removeFromOld` | boolean | `false` | When `true`, deletes all source entries after copying |
| `async` | boolean | `false` | When `true`, write runs in background |

Returns `{ ok, moved, removed_from_old }` where `moved` is the number of fields copied.

```javascript theme={null}
var result = moveCrmToEntity({
  fromSlug: 'leads',
  toSlug: 'deals',
  fieldMap: {
    lead_score: 'initial_score',
    source: 'lead_source'
  },
  pipelineSlug: 'sales',
  stageSlug: 'new',
  removeFromOld: false
});

if (result.ok) {
  console.log(result.moved, 'fields copied');
}
```


# Examples
Source: https://docs.elasticfunnels.io/backend-scripts/examples

Common patterns and real-world examples for backend scripts.

## Access control — require login

Redirect visitors who haven't purchased to a sales page:

```html theme={null}
<script scope="backend">
  if (!is_customer) {
    redirect('/sales-page');
  }
</script>

<h1>Welcome to your dashboard, {{ customer.name }}</h1>
```

## Promo code from URL

Check for a promo query parameter and set discount variables:

```html theme={null}
<script scope="backend">
  var promo = request.query.promo;

  if (promo === 'VIP50') {
    setVariable('discount', '50%');
    setVariable('show_promo_banner', true);
    session.set('applied_promo', promo);
  } else if (promo === 'WELCOME20') {
    setVariable('discount', '20%');
    setVariable('show_promo_banner', true);
    session.set('applied_promo', promo);
  } else {
    setVariable('discount', '0%');
    setVariable('show_promo_banner', false);
  }
</script>

@if(var.show_promo_banner)
  <div class="promo-banner">
    Use code for {{ var.discount }} off!
  </div>
@endif
```

## Geo-based redirect

Redirect mobile visitors to a mobile-optimized page:

```html theme={null}
<script scope="backend">
  if (request.is_mobile && request.path === '/sales') {
    redirect('/sales-mobile');
  }
</script>
```

## Product-aware logic

Check if a product exists and set variables based on its properties:

```html theme={null}
<script scope="backend">
  var product = getProduct('premium-plan');

  if (!product) {
    response.status(404);
    response.send('<h1>Product not found</h1>');
  }

  setVariable('product_name', product.name);
  setVariable('product_price', product.price);
  setVariable('is_subscription', product.is_subscription ? true : false);
</script>

<h1>{{ var.product_name }}</h1>
<p>Price: ${{ var.product_price }}</p>

@if(var.is_subscription)
  <p>This is a recurring subscription.</p>
@endif
```

## Returning customer detection

Check order history and personalize the page:

```html theme={null}
<script scope="backend">
  if (is_customer && customer.email) {
    var orders = getOrders('newest', 1);

    if (orders.length > 0) {
      setVariable('returning', true);
      setVariable('last_order_date', orders[0].created_at);
    }
  }
</script>

@if(var.returning)
  <div class="welcome-back">
    Welcome back! Your last order was on {{ var.last_order_date }}.
  </div>
@else
  <div class="new-visitor">
    Welcome! Check out our products.
  </div>
@endif
```

## Course access gate

Only allow access if the visitor has purchased the course product:

```html theme={null}
<script scope="backend">
  if (!is_customer) {
    redirect('/courses/pricing');
  }

  var orders = getOrders('newest', 100);
  var hasCourseAccess = false;

  for (var i = 0; i < orders.length; i++) {
    var products = orders[i].products;
    for (var j = 0; j < products.length; j++) {
      if (products[j].name === 'Course Access Pass') {
        hasCourseAccess = true;
      }
    }
  }

  if (!hasCourseAccess) {
    redirect('/courses/pricing');
  }

  var course = getCourseBySlug('javascript-basics');
  if (course) {
    setVariable('course_title', course.title);
    setVariable('total_lessons', course.total_lesson_count);
  }
</script>

<h1>{{ var.course_title }}</h1>
<p>{{ var.total_lessons }} lessons</p>
```

## JSON API endpoint

Use a page as a lightweight JSON API:

```html theme={null}
<script scope="backend">
  if (request.method !== 'GET') {
    response.status(405);
    response.json({ error: 'Method not allowed' });
  }

  var products = getAllProducts();
  var catalog = [];

  for (var i = 0; i < products.length; i++) {
    catalog.push({
      name: products[i].name,
      price: products[i].price,
      code: products[i].code
    });
  }

  response.json({ products: catalog });
</script>
```

## Blog listing with backend logic

Fetch blog articles and inject them as template variables:

```html theme={null}
<script scope="backend">
  var blog = getBlog();
  if (!blog) {
    response.status(404);
    response.send('<h1>Blog not found</h1>');
  }

  var page = parseInt(request.query.page) || 1;
  var articles = getBlogArticles(blog.id, page, 12);
  var categories = getBlogCategories(blog.id);

  setVariable('blog_name', blog.name);
  setVariable('articles', articles);
  setVariable('categories', categories);
  setVariable('current_page', page);
</script>

<h1>{{ var.blog_name }}</h1>
```

## Product catalog with savings badges

```html theme={null}
<script scope="backend">
  var products = getProducts({ type: 'physical' });
  var catalog = [];

  for (var i = 0; i < products.length; i++) {
    var p = products[i];
    var savings = productSavings(p);

    catalog.push({
      name: p.name,
      price: formatPrice(p.price, p.currency),
      badge: savings.percent > 0 ? 'Save ' + savings.percentFormatted : '',
      buy_url: buy(p.code),
      subscription_info: subscriptionSummary(p)
    });
  }

  setVariable('catalog', catalog);
</script>
```

## Course access with session items

Share state between backend scripts and template-engine expressions:

```html theme={null}
<script scope="backend">
  if (!is_customer) {
    redirect('/courses/pricing');
  }

  var slug = request.query.course || 'default-course';
  var course = getCourseBySlug(slug);

  if (course) {
    setVariable('course', course);
    setSessionItem('last_viewed_course', slug);
  }

  var categories = getCategoriesWithCourses();
  setVariable('categories', categories);
</script>
```

## Whitelist admin visitors

```html theme={null}
<script scope="backend">
  var customer = getCustomer();

  if (customer && customer.email === 'admin@mybrand.com') {
    whitelistVisitor();
    setVariable('is_admin', true);
  }
</script>
```

## Shared auth guard with imports

Create a backend script module (code: `auth`) with reusable access-control helpers:

```javascript theme={null}
export function requireCustomer() {
  if (!is_customer) {
    redirect('/login');
  }
}

export function requireAdmin(email) {
  var admins = ['admin@mybrand.com', 'support@mybrand.com'];
  for (var i = 0; i < admins.length; i++) {
    if (admins[i] === email) return true;
  }
  redirect('/unauthorized');
}
```

Then use it on any page — no need to duplicate the logic:

```html theme={null}
<script scope="backend">
  import { requireCustomer, requireAdmin } from "auth";

  requireCustomer();
  requireAdmin(customer.email);

  setVariable('admin_name', customer.name);
</script>

<h1>Admin Dashboard — {{ var.admin_name }}</h1>
```

You can also build a shared utility module (code: `utils`):

```javascript theme={null}
export function slugify(text) {
  return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
}

export function truncate(str, len) {
  if (str.length <= len) return str;
  return str.substring(0, len) + '...';
}
```

```html theme={null}
<script scope="backend">
  import { slugify, truncate } from "utils";

  var articles = getBlogArticles(1, 1, 10);
  var items = [];

  for (var i = 0; i < articles.length; i++) {
    items.push({
      title: articles[i].title,
      excerpt: truncate(articles[i].body, 120),
      url: '/blog/' + slugify(articles[i].title)
    });
  }

  setVariable('articles', items);
</script>
```

See [Imports](/backend-scripts/imports) for the full reference on `import` / `export` syntax and resolution rules.

## External API with proxy

Verify a token with an external service (requires HTTP proxy to be configured):

```html theme={null}
<script scope="backend">
  if (typeof http === 'undefined') {
    console.error('HTTP proxy not configured');
    redirect('/error');
  }

  var token = request.query.auth;
  if (!token) {
    redirect('/login');
  }

  var result = http.get(
    'https://api.myservice.com/verify?token=' + token,
    { 'Authorization': 'Bearer my-api-key' }
  );

  if (result.status === 200) {
    var user = JSON.parse(result.body);
    session.set('external_user_id', user.id);
    session.set('external_user_name', user.name);
    setVariable('user_name', user.name);
  } else {
    response.status(403);
    response.send('<h1>Authentication failed</h1>');
  }
</script>

<h1>Hello, {{ var.user_name }}</h1>
```


# HTTP Requests
Source: https://docs.elasticfunnels.io/backend-scripts/http

Make HTTP GET and POST requests to external APIs from backend scripts.

Backend scripts can make HTTP requests to external APIs using `http.get()` and `http.post()`. All requests are routed through a secure proxy to prevent direct access to internal infrastructure.

<Warning>
  HTTP functions are only available when the HTTP proxy is configured. If the proxy is not set up, `http` will be `undefined`. Contact your administrator to enable this feature.
</Warning>

## `http.get(url, headers?)`

Make an HTTP GET request.

```javascript theme={null}
var result = http.get('https://api.example.com/user/123');

if (result.status === 200) {
  var data = JSON.parse(result.body);
  setVariable('user_name', data.name);
}
```

| Parameter | Type | Description |
| - | - | - |
| `url` | string | Full URL to request |
| `headers` | object | Optional request headers |

## `http.post(url, body, headers?)`

Make an HTTP POST request.

```javascript theme={null}
var result = http.post(
  'https://api.example.com/verify',
  JSON.stringify({ token: request.query.token }),
  { 'Content-Type': 'application/json' }
);

if (result.status !== 200) {
  redirect('/unauthorized');
}
```

| Parameter | Type | Description |
| - | - | - |
| `url` | string | Full URL to request |
| `body` | string | Request body (typically JSON stringified) |
| `headers` | object | Optional request headers |

## Response object

Both `http.get` and `http.post` return an object:

```javascript theme={null}
{
  status: 200,          // HTTP status code (0 if request failed entirely)
  headers: {},          // Response headers
  body: '...'           // Response body as a string
}
```

To work with JSON APIs, parse the body:

```javascript theme={null}
var result = http.get('https://api.example.com/data');
var data = JSON.parse(result.body);
```

## Limits

| Constraint | Value |
| - | - |
| Max requests per script execution | 5 |
| Request timeout | 10 seconds |
| Max response body size | 1 MB |

## Security

* All requests are routed through an authenticated proxy — they never originate from the application server directly
* Private/internal IPs are blocked (localhost, 10.x.x.x, 172.16-31.x.x, 192.168.x.x, 169.254.x.x, AWS metadata endpoint)
* Only `http://` and `https://` protocols are allowed

## Example: external auth check

```html theme={null}
<script scope="backend">
  var token = request.query.token;

  if (!token) {
    redirect('/login');
  }

  var auth = http.post('https://auth.myservice.com/validate',
    JSON.stringify({ token: token }),
    { 'Content-Type': 'application/json' }
  );

  if (auth.status === 200) {
    var user = JSON.parse(auth.body);
    session.set('verified_user', user.email);
    setVariable('user_name', user.name);
  } else {
    response.status(403);
    response.send('<h1>Invalid token</h1>');
  }
</script>

<h1>Welcome, {{ var.user_name }}</h1>
```


# Imports
Source: https://docs.elasticfunnels.io/backend-scripts/imports

Share and reuse code between backend scripts by importing from other pages.

Backend scripts support `import` / `export` syntax to share functions, constants, and objects between pages. Create a "module" page with exported code, then import what you need in any other page's backend script.

## Quick example

Create a page (e.g. slug `app`) with shared functions:

```html theme={null}
<script scope="backend">
  export const getGreeting = function (name) {
    return 'Hello, ' + name + '!';
  };

  export function isAdmin(email) {
    return email === 'admin@mybrand.com';
  }
</script>
```

Import and use them in another page:

```html theme={null}
<script scope="backend">
  import { getGreeting, isAdmin } from "app";

  if (customer && customer.email) {
    setVariable('greeting', getGreeting(customer.name));
    setVariable('is_admin', isAdmin(customer.email));
  }
</script>

<h1>{{ var.greeting }}</h1>
```

## Import specifier formats

All of these resolve to the same page slug `app`:

```javascript theme={null}
import { test } from "app";        // bare name
import { test } from "app.js";     // with .js extension
import { test } from "../app.js";  // relative path
import { test } from "./app";      // relative path
```

The resolution rules:

1. The `.js` extension is stripped
2. Leading `./` or `../` prefixes are stripped
3. The remaining string is used as the page slug to look up

For nested pages, the slug path is preserved:

```javascript theme={null}
import { helper } from "utils/helpers";  // resolves to page slug "utils/helpers"
```

## Named imports

Import specific exports by name:

```javascript theme={null}
// Module page (slug: "utils")
export const TAX_RATE = 0.08;
export function calculateTax(amount) {
  return amount * TAX_RATE;
}
export function formatCurrency(val) {
  return '$' + val.toFixed(2);
}
```

```javascript theme={null}
// Importing page
import { calculateTax, formatCurrency } from "utils";

var price = 49.99;
var tax = calculateTax(price);
setVariable('total', formatCurrency(price + tax));
```

## Default imports

Use `export default` for a module's primary export:

```javascript theme={null}
// Module page (slug: "config")
export default {
  siteName: 'My Store',
  supportEmail: 'help@mystore.com',
  maxItems: 10
};
```

```javascript theme={null}
// Importing page
import config from "config";

setVariable('site_name', config.siteName);
setVariable('support_email', config.supportEmail);
```

## Multiple modules

Import from several pages in the same script:

```html theme={null}
<script scope="backend">
  import { isAdmin } from "auth";
  import { getGreeting } from "helpers";
  import config from "config";

  if (customer && isAdmin(customer.email)) {
    setVariable('greeting', getGreeting(customer.name));
    setVariable('site', config.siteName);
  }
</script>
```

## Module pages work on their own

A page with `export` statements still works when visited directly — the `export` keywords are silently stripped before execution. This means you can add `setVariable` calls alongside exports for the module page's own rendering:

```html theme={null}
<script scope="backend">
  export function getPlans() {
    return getAllProducts({ classification: 'subscription' });
  }

  // This runs when the module page is visited directly
  var plans = getPlans();
  setVariable('plan_count', plans.length);
</script>

<p>We offer {{ var.plan_count }} subscription plans.</p>
```

When another page imports `getPlans`, only the function is used — the `setVariable` call in the module runs inside the importing page's context too (both scripts share the same sandbox).

## Supported export syntax

| Syntax | Supported |
| - | - |
| `export const name = ...` | Yes |
| `export let name = ...` | Yes |
| `export var name = ...` | Yes |
| `export function name() { ... }` | Yes |
| `export async function name() { ... }` | Yes |
| `export class Name { ... }` | Yes |
| `export default ...` | Yes |
| `export { name1, name2 }` | Yes |

## Limits

| Constraint | Value |
| - | - |
| Max imports per script | 10 |
| Import depth | 1 level (nested imports inside modules are not resolved) |

### Supported import shapes

Each `import` line must be **either** a default import **or** a named import — not both on the same line:

```javascript theme={null}
import { Greeter, wrap } from "app";   // named — OK
import config from "config";           // default only — OK
// import Greeter, { wrap } from "app";  // not supported — use named exports only, or split across modules
```

You can combine **classes and functions** from the same module with named imports, or import a class from one module and helpers from another.

Exported functions may return **nested objects**, **arrays of objects**, or build structures from parameters — this is fully supported after inlining:

```javascript theme={null}
// Module
export function getPayload() {
  return { user: { name: 'Pat' }, items: [{ id: 1 }] };
}
export const config = { api: { version: 2 } };
export function merge(input) {
  return { out: { a: input.a || 0 } };
}
```

## How imports work

When a backend script contains `import` statements:

1. Import statements are parsed and removed from the script
2. Each module specifier is normalized to a page slug
3. The module page's `<script scope="backend">` code is fetched
4. `export` keywords are stripped from the module code, turning exports into regular declarations
5. The module code is prepended to the importing script
6. The combined code runs as a single script in the sandbox

Imported code is **merged into your script before it runs** — it is not loaded separately at runtime. It shares the same scope as the importing script, with access to the same globals (`setVariable`, `session`, `request`, etc.).


# Backend Scripts
Source: https://docs.elasticfunnels.io/backend-scripts/overview

Run custom server-side JavaScript on any page — access control, session logic, API calls, and dynamic variables — fully sandboxed.

Backend Scripts let you run custom JavaScript **on the server** before a page is rendered. The code runs in a secure, isolated sandbox with no access to the file system, host runtime APIs, or your infrastructure beyond the documented functions.

Use them for logic that must happen **before** the visitor sees the page — access control, custom redirects, session manipulation, calling external APIs, or injecting dynamic template variables.

## How it works

Add a `<script scope="backend">` tag anywhere in your page HTML. The server extracts and runs the code **before** funnel events and template rendering. The tag is always stripped from the final HTML — it never reaches the browser.

```html theme={null}
<script scope="backend">
  if (!is_customer) {
    redirect('/login');
  }

  setVariable('greeting', 'Welcome back, ' + customer.name);
</script>

<div class="hero">
  <h1>{{ var.greeting }}</h1>
</div>
```

## Execution order

Backend scripts run early in the page lifecycle, before funnel events:

1. Page resolved and loaded
2. Access control checked
3. **Backend script extracted, stripped from HTML, and executed**
4. Funnel events processed (script rules, splits, etc.)
5. Template engine renders the page
6. HTML sent to visitor

Because backend scripts run before funnel events, session values you set are visible to script rules and other funnel nodes downstream.

## Sandboxing & security

Backend scripts run inside a **locked-down sandbox**. This means:

* No access to `process`, `require`, `fs`, `net`, or similar host APIs
* No access to the file system or private networks
* **8 MB memory limit** per execution
* **10 second CPU timeout** — pure JavaScript execution stops if it exceeds this
* **30 second wall-clock timeout** — the entire run (including data loads and HTTP calls) stops if it exceeds this
* The `<script scope="backend">` tag is **always** removed from the HTML, even if execution fails
* Session and cookie writes are limited to safe, documented keys
* Redirects are limited to relative paths and `http://` / `https://` URLs
* Response headers and cookie access are restricted for security

The sandbox provides a controlled set of host functions (documented below) that bridge back to the server safely. User code cannot escape the sandbox or access anything beyond these APIs.

## When a script throws or times out

If your backend script throws an error or hits a timeout, the **visitor does not see the error message**. The page continues to render as normal. Any variables or actions your script applied before the error are still used; anything after the error is skipped. Failures are recorded for your team to review in logs. For development, use `console.log()` and check your backend or event logs.

## Multiple script blocks

You can have multiple `<script scope="backend">` tags on a page. They are concatenated in document order and executed as a single script.

## Importing shared modules

You can share reusable functions and constants across pages using backend script modules. Create a module in your brand's **Backend Scripts** section (with a code like `app` or `utils`), then import from it:

```html theme={null}
<script scope="backend">
  import { isAdmin, getGreeting } from "app";

  if (is_customer && isAdmin(customer.email)) {
    setVariable('greeting', getGreeting(customer.name));
  }
</script>
```

Modules are standalone JavaScript with `export` statements, managed separately from pages. See [Imports](/backend-scripts/imports) for the full reference.


# Queue
Source: https://docs.elasticfunnels.io/backend-scripts/queue

Deferred background script execution with tag-based cancellation.

Backend scripts can schedule other scripts to run in the background after a delay using the `queue` global. Jobs are stored in Redis and processed by a background worker. This is useful for sending follow-up emails, scheduling reminders, or any task that should happen later without blocking the current request.

## `queue.push(scriptCode, payload, opts?)`

Enqueue a backend script for deferred execution.

```javascript theme={null}
// Send an abandon email 1 hour after quiz completion
queue.push('mailgun', {
  type: 'abandon',
  email: 'user@example.com',
  quizProfile: quizProfile,
  visitorId: visitorId,
}, { delay: 3600, tag: 'abandon:' + visitorId });
```

| Parameter | Type | Description |
| - | - | - |
| `scriptCode` | string | The backend script code to execute (e.g. `'mailgun'`) |
| `payload` | object | Data passed to the script's exported function |
| `opts` | object | Optional configuration (see below) |

### Options

| Key | Type | Default | Description |
| - | - | - | - |
| `fn` | string | `'default'` | Name of the exported function to call |
| `delay` | number | `0` | Seconds to wait before executing. Minimum **60s** when non-zero, maximum **7 days** (604,800s) |
| `tag` | string | — | Logical group for cancellation (max 200 chars) |

**Returns:** `{ ok: true, jobId: '...' }` on success, or `{ ok: false, error: '...' }` on failure.

### How the target script is called

The queued script's exported function receives the `payload` object as its only argument:

```javascript theme={null}
// scripts/mailgun.js
function handleQueuedEmail(data) {
  if (data.type === 'abandon') {
    sendAbandonEmail(data.email, data.quizProfile, data.visitorId);
  } else {
    sendResultsEmail(data.email, data.quizProfile);
  }
}
export default handleQueuedEmail;
```

If you specify `opts.fn`, a named export is called instead of the default export:

```javascript theme={null}
queue.push('my-script', { userId: 123 }, { fn: 'processUser', delay: 60 });
// → calls my-script.processUser({ userId: 123 }) after 60 seconds
```

## `queue.cancel(tag)`

Cancel all pending jobs with the given tag for the current brand.

```javascript theme={null}
var result = queue.cancel('abandon:' + visitorId);
console.log('Cancelled', result.cancelled, 'jobs');
```

| Parameter | Type | Description |
| - | - | - |
| `tag` | string | The tag to cancel |

**Returns:** `{ ok: true, cancelled: N }` where N is the number of jobs removed.

## Example: Multi-step abandon email sequence

Queue 3–4 emails spaced over a few days. Cancel the whole sequence on purchase using the shared tag prefix.

```javascript theme={null}
// On email capture — queue the abandon sequence
var tag = 'abandon:' + visitorId;

queue.push('mailgun', { type: 'abandon_1', email: leadEmail, quizProfile: quizProfile, visitorId: visitorId },
  { delay: 3600,  tag: tag }); // 1 hour

queue.push('mailgun', { type: 'abandon_2', email: leadEmail, quizProfile: quizProfile, visitorId: visitorId },
  { delay: 86400, tag: tag }); // 24 hours

queue.push('mailgun', { type: 'abandon_3', email: leadEmail, quizProfile: quizProfile, visitorId: visitorId },
  { delay: 172800, tag: tag }); // 48 hours

queue.push('mailgun', { type: 'abandon_4', email: leadEmail, quizProfile: quizProfile, visitorId: visitorId },
  { delay: 259200, tag: tag }); // 72 hours

// On purchase — cancel all pending emails in one call
queue.cancel(tag);
```

<Note>
  **Limits per brand:**

  * **25,000 pending jobs** maximum per brand
  * **64 KB** maximum payload size
  * **7-day** maximum delay (604,800 seconds)
  * **60-second** minimum delay when a non-zero delay is set
  * **5 pushes** per script execution
  * **5 cancel calls** per script execution
  * **3 retries** with exponential backoff on failure
  * Jobs expire after **8 days** if not processed
</Note>

<Warning>
  Queued scripts run in a background worker **without session or customer context**. They have access to `cache`, `queue`, and CRM functions, but **not** `request`, `session`, `redirect`, or `response`. Design your scripts to receive all needed data in the `payload`.
</Warning>


# Storage
Source: https://docs.elasticfunnels.io/backend-scripts/storage

Durable, database-backed key-value store for backend scripts.

Backend scripts have access to a durable key-value store via the `storage` global. Values are persisted to the database, so they **survive restarts and deploys** and are readable from **every runtime server immediately** — there's no per-server cache to warm and no worker to run.

Every key is automatically scoped to the current brand — scripts can never read or write another brand's data. Values are JSON-serialised, so you can store strings, numbers, booleans, arrays, and plain objects.

## Storage vs. Cache

Both are brand-scoped key-value APIs, but they solve different problems:

| | `storage` | `cache` |
| - | - | - |
| Backing store | Database (durable) | Redis (in-memory) |
| Survives restarts | **Yes** | Until eviction / TTL |
| Default lifetime | Permanent (no expiry) | 1 hour |
| Max value size | 64 KB | 512 bytes |
| Best for | Tokens, settings, cursors, idempotency markers | Hot counters, short-lived dedupe, rate windows |

<Tip>
  Reach for `cache` for high-frequency, disposable data. Reach for `storage` when losing the value would break something — OAuth refresh tokens, sync cursors, "have I already processed this?" markers.
</Tip>

## Options

Every method takes an optional trailing `opts` object:

| Field | Type | Default | Description |
| - | - | - | - |
| `namespace` | string | `'default'` | Groups keys (e.g. per integration). Isolated per namespace. |
| `ttl` | number | — | Seconds until the value expires. Omit for permanent. |

## `storage.get(key, opts?)`

Retrieve a value.

```javascript theme={null}
var settings = storage.get('config', { namespace: 'aweber' });
if (settings) {
  setVariable('list_id', settings.list_id);
}
```

**Returns:** The stored value, or `null` if the key is missing or expired.

## `storage.set(key, value, opts?)`

Store a value, overwriting any existing one.

```javascript theme={null}
storage.set('sync_cursor', { page: 3, updated_at: Date.now() });
storage.set('access_token', token, { namespace: 'aweber', ttl: 7200 });
```

| Parameter | Type | Description |
| - | - | - |
| `key` | string | Storage key |
| `value` | any | Value to store (JSON-serialised) |
| `opts` | object | `{ namespace?, ttl? }` |

**Returns:** `true` on success, `false` if the brand key limit was reached.

## `storage.del(key, opts?)`

Delete a key.

```javascript theme={null}
storage.del('sync_cursor');
```

**Returns:** `true`.

## `storage.has(key, opts?)`

Check whether a live (non-expired) key exists.

```javascript theme={null}
if (!storage.has('seeded', { namespace: 'import' })) {
  // first run — do one-time setup
}
```

**Returns:** `true` if the key exists and has not expired, `false` otherwise.

## `storage.setIfAbsent(key, value, opts?)`

Write a value **only if the key is absent or expired**. This is atomic (row-locked), which makes it a reliable short-lived **mutex** across all runtime servers.

```javascript theme={null}
// Ensure only one server sends the welcome email, ever.
var isFirst = storage.setIfAbsent('welcome_sent:' + email, true, { namespace: 'email' });
if (isFirst) {
  // send it
}
```

**Returns:** `true` if the value was written, `false` if a live value already existed.

## `storage.compareAndSet(key, expected, next, opts?)`

Atomically set `next` **only if** the current stored value equals `expected` (compared by value). A missing or expired key is treated as `null`. Use this for lock-free optimistic updates where a stale writer must not clobber newer data.

```javascript theme={null}
var current = storage.get('rotating_config');
var updated = Object.assign({}, current, { version: 5 });

var ok = storage.compareAndSet('rotating_config', current, updated);
if (!ok) {
  // someone else updated it first — re-read and retry
}
```

| Parameter | Type | Description |
| - | - | - |
| `key` | string | Storage key |
| `expected` | any | Value you expect to currently be stored |
| `next` | any | Value to write if `expected` still matches |
| `opts` | object | `{ namespace?, ttl? }` |

**Returns:** `true` if the swap happened, `false` if the current value didn't match `expected`.

## `storage.increment(key, amount?, opts?)`

Atomically add to a numeric value, creating it (starting at `0`) if absent.

```javascript theme={null}
var total = storage.increment('lifetime_signups');
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `key` | string | — | Storage key |
| `amount` | number | 1 | Value to add (can be negative or float) |
| `opts` | object | — | `{ namespace?, ttl? }` |

**Returns:** The new numeric value after incrementing.

## `storage.mutate(key, fn, opts?)`

Atomically read a value, transform it, and write the result — the safe way to do read-modify-write without losing a concurrent update. `fn` receives the current value (`undefined` if the key is absent) and returns the value to store. Returning `undefined` aborts the write and leaves the stored value untouched.

```javascript theme={null}
// Append to a durable list without clobbering a concurrent run.
storage.mutate('recent_orders', function (list) {
  list = list || [];
  list.unshift(orderId);
  return list.slice(0, 50);
});
```

Under the hood this is an **optimistic loop**: read the current value, run `fn`, then commit with a row-locked `compareAndSet`. If another execution wrote first, it re-reads and runs `fn` again (a few times) until it commits cleanly.

| Parameter | Type | Description |
| - | - | - |
| `key` | string | Storage key |
| `fn` | function | `(current) => next`. Return `undefined` to abort. |
| `opts` | object | `{ namespace?, ttl? }` |

**Returns:** The newly stored value (or the unchanged value if `fn` returned `undefined`). Throws if it still can't commit after several retries (extreme contention).

<Warning>
  Because `fn` can run **more than once** (on retry), it must be a **pure function of its input** — derive `next` only from `current`. Do **not** put one-time side effects inside `fn` (spending a single-use token, sending an email, charging a card). For exactly-once side effects, use the claim pattern shown below.
</Warning>

## Example: rotating OAuth refresh tokens (exactly-once)

The motivating case. Providers like AWeber hand out a **short-lived access token** plus a **single-use refresh token that rotates on every refresh** — using the old refresh token invalidates it. Two guarantees are needed, and `storage` gives you both:

1. **Durability** — the newly rotated refresh token must be persisted for the next run (backend scripts are stateless; there's nowhere else to keep it).
2. **Exactly-once refresh** — if two requests refresh at the same instant, they'd both spend the *same* single-use refresh token and one call would fail. Only one request may perform the refresh.

The fool-proof approach is **refresh-ahead + a claim**:

* Refresh *before* the access token actually expires (while it's still valid), so a request that doesn't win the claim can safely keep using the current token — no waiting.
* Use `setIfAbsent` as a **non-blocking claim**: exactly one request wins and refreshes; the others fall through. Because a claim can never outlive its TTL, a crashed run can't wedge the integration.

```javascript theme={null}
var NS = 'integrations';
var creds = storage.get('aweber_oauth', { namespace: NS }) || {};
var now = Date.now();
var REFRESH_AHEAD_MS = 5 * 60 * 1000; // refresh 5 min before expiry

var needsRefresh = !creds.access_token || now >= ((creds.expires_at || 0) - REFRESH_AHEAD_MS);

if (needsRefresh) {
  // Non-blocking claim — only the winner refreshes. TTL releases it if a run dies.
  var claimed = storage.setIfAbsent('aweber_refresh_claim', now, { namespace: NS, ttl: 30 });

  if (claimed) {
    var res = http.post('https://auth.aweber.com/oauth2/token', {
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: 'grant_type=refresh_token&refresh_token=' + encodeURIComponent(creds.refresh_token),
    });

    if (res.status >= 200 && res.status < 300) {
      creds = {
        access_token:  res.body.access_token,
        refresh_token: res.body.refresh_token,        // rotated — persisted for the next run
        expires_at:    now + (res.body.expires_in * 1000),
      };
      storage.set('aweber_oauth', creds, { namespace: NS });
    }
    storage.del('aweber_refresh_claim', { namespace: NS });
  }
  // Didn't win the claim? Fall through — the current token is still valid
  // (that's the point of refreshing ahead of expiry).
}

// creds.access_token is valid here — make the API call.
```

<Note>
  **Why not refresh *inside* a locked callback?** Two reasons: holding a database lock across an external network call is an anti-pattern, and the script sandbox can only wait on **one** async operation at a time — a network call nested inside a locked callback isn't supported and would fail. Keep the network call in your main script flow, guarded by a claim.
</Note>

<Note>
  **Limits per brand:**

  * **10,000 keys** maximum per brand
  * **64 KB** maximum value size
  * **No expiry by default** (max TTL when set: 1 year)
  * **50 storage operations** per script execution (a `mutate` retry spends a `get` + a `compareAndSet`)
</Note>

<Warning>
  Keys must match the pattern `[a-zA-Z0-9_.:-]` and be at most 191 characters. Namespaces follow the same pattern up to 64 characters. Values that don't fit, or keys/namespaces that don't match, are rejected.
</Warning>


# Tags
Source: https://docs.elasticfunnels.io/backend-scripts/tags

Read, add and remove visitor tags from a backend script — the same tags the Tag User and Has Tag funnel nodes use.

Tags mark a visitor so a later page or funnel step can branch on them: `seen_vsl`, `declined_upsell`, `vip`. Backend scripts get four functions for working with the same tags the [Tag User and Has Tag nodes](/funnels/page-events-nodes) set and read.

```javascript theme={null}
if (!hasTag('seen_offer')) {
  addTag('seen_offer', 10080); // 7 days
  setVariable('first_visit', true);
}
```

## `hasTag(name)`

Returns `true` if the visitor carries the tag, `false` otherwise. Finds tags set by the Tag User node, by `ef.addTag()` in the browser, and by `addTag()` below.

```javascript theme={null}
if (hasTag('vip')) {
  setVariable('discount', 20);
}
```

## `addTag(name, expirationMinutes?)`

Adds a tag. Returns `true` if it was added, `false` if the name was rejected or the per-execution cap was hit.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | string | — | Tag name. Letters, digits, `_`, `-`, `.`, `:`; max 120 characters |
| `expirationMinutes` | number | — | Omit or pass `0` for a session tag; a positive number expires the tag after that many minutes |

```javascript theme={null}
addTag('abandoned_cart');           // until the browser session ends
addTag('trial_started', 10080);     // 7 days
addTag('promo_seen', 60);           // 1 hour
```

## `removeTag(name)`

Removes a tag. Returns `true` if the removal was queued, `false` if the name was rejected. Removing a tag the visitor does not have is not an error.

```javascript theme={null}
removeTag('abandoned_cart');
```

## `getTags()`

Returns an array of the visitor's tag names.

```javascript theme={null}
setVariable('tag_count', getTags().length);
```

<Note>
  `getTags()` lists tags written by `addTag()` and by `ef.addTag()` in the browser. Tags written by the **Tag User** node are stored under a bare cookie name that is indistinguishable from any other cookie, so they cannot be enumerated — `hasTag('name')` still finds them.
</Note>

## Reserved and invalid names

`addTag()` and `removeTag()` return `false` without doing anything when the name is empty, longer than 120 characters, contains characters that are not valid in a cookie name (spaces, `;`, `=`), or collides with a reserved cookie such as `hop`, `subid`, `aff` or the session cookie. This stops a tag from overwriting affiliate or session state.

```javascript theme={null}
addTag('hop');          // false — reserved
addTag('my tag');       // false — space is not a valid cookie-name character
addTag('cart_started'); // true
```

## A tag is visible immediately

A tag added by a backend script is visible to the rest of that same script, and to funnel nodes that run after it on the same request:

```javascript theme={null}
addTag('qualified');
hasTag('qualified'); // true — right away
```

<Warning>
  The **Tag User** node behaves differently: a tag it sets is only visible to a **Has Tag** node on the *next* request, not the one it was set on. If you need set-then-branch inside a single page load, set the tag with `addTag()` in a backend script rather than with a Tag User node.
</Warning>

## How tags are stored

Tags are plain, unencrypted cookies. Two naming conventions exist for historical reasons:

| Written by | Cookie name |
| - | - |
| **Tag User** node (server) | `vip` |
| `ef.addTag()` (browser) | `tag_vip` |
| `addTag()` (backend script) | both `vip` and `tag_vip` |

`addTag()` writes both names so a tag set from a backend script is visible everywhere — the Has Tag node, `ef.hasTag()` in the browser, and the `tags` array in Script Rules. `hasTag()` and `removeTag()` accept either spelling, so you do not have to think about which side set a tag.

<Warning>
  Because tags are unencrypted cookies, a visitor can add or remove their own tags from the browser console. Use them for funnel flow and personalization — never as the only gate on paid content, pricing, or anything else where forging a tag would cost you.
</Warning>

## Example: one-time offer

Show an offer once, then never again for 30 days.

```html theme={null}
<script scope="backend">
if (hasTag('flash_offer_seen')) {
  setVariable('show_offer', false);
} else {
  addTag('flash_offer_seen', 43200); // 30 days
  setVariable('show_offer', true);
}
</script>
```

## Example: clearing a tag after purchase

```html theme={null}
<script scope="backend">
if (is_customer && hasTag('abandoned_cart')) {
  removeTag('abandoned_cart');
  queue.cancel('abandon:' + customer.email);
}
</script>
```

See [Queue](/backend-scripts/queue) for the cancellation tag used here — that is a job-grouping label, unrelated to visitor tags.

## Limits

* **50** tag writes per script execution. `addTag()` and `removeTag()` return `false` past that.
* Each `addTag()` and `removeTag()` emits an `add-tag` / `remove-tag` tracking event, the same as the Tag User node and `ef.addTag()`.


# Schema Validator
Source: https://docs.elasticfunnels.io/backend-scripts/validation

Built-in Joi-like Schema API for validating data in backend scripts — type-safe, sandbox-native, zero dependencies.

A `Schema` validation library is available globally in every backend script. It provides a **Joi-like fluent API** to validate, coerce, and sanitize incoming data — especially `request.body` from POST requests, but usable with any object.

The library is pure JavaScript and runs directly in the sandbox. No imports needed — `Schema` is a global.

## Quick start

```javascript theme={null}
var schema = Schema.object({
  name:   Schema.string().required().min(1).max(255),
  email:  Schema.string().required().email(),
  weight: Schema.number().min(50).max(500),
});

var result = schema.validate(request.body);

if (!result.valid) {
  response.json({ ok: false, errors: result.errors });
}

// result.value is a sanitised deep copy — safe to use
setCrmField({ slug: 'my-entity-slug', fieldKey: 'name', value: result.value.name });
setCrmField({ slug: 'my-entity-slug', fieldKey: 'current_weight', value: result.value.weight });
```

## How it works

1. Define a schema using `Schema.string()`, `Schema.number()`, etc.
2. Chain validators: `.required()`, `.min(5)`, `.email()`, etc.
3. Call `schema.validate(data)` — returns `{ valid, value, errors }`
4. If `valid` is `true`, `value` contains a **deep-cloned, type-coerced** copy of the input
5. If `valid` is `false`, `errors` is an array of human-readable error messages

<Note>
  `validate()` returns a **deep clone** of the input. The original `request.body` is never mutated. Unknown keys in objects are silently dropped — only keys defined in the schema are kept.
</Note>

## Types

### `Schema.string()`

Validates that the value is a string.

```javascript theme={null}
Schema.string()                        // any string
Schema.string().required()             // non-empty required
Schema.string().min(3).max(100)        // length constraints
Schema.string().email()                // email format
Schema.string().url()                  // http/https URL
Schema.string().pattern(/^[A-Z]+$/)   // regex match
Schema.string().lowercase()            // must be lowercase
Schema.string().valid('a', 'b', 'c')   // enum — must be one of these
```

### `Schema.number()`

Validates that the value is a number. Strings like `"42"` are auto-coerced.

```javascript theme={null}
Schema.number()                        // any finite number
Schema.number().integer()              // no decimals
Schema.number().min(0)                 // >= 0
Schema.number().max(100)               // <= 100
Schema.number().positive()             // > 0
Schema.number().negative()             // < 0
```

### `Schema.boolean()`

Validates that the value is a boolean. Strings `"true"`, `"1"`, `"false"`, `"0"` are auto-coerced.

```javascript theme={null}
Schema.boolean()
Schema.boolean().required()
```

### `Schema.array()`

Validates arrays. Use `.items()` to validate each element.

```javascript theme={null}
Schema.array()                                          // any array
Schema.array().min(1).max(10)                           // length constraints
Schema.array().items(Schema.string().max(50))           // typed elements
Schema.array().items(Schema.number().min(0)).max(100)   // numbers array, max 100 items
```

### `Schema.object()`

Validates objects. Pass a key map to define the shape.

```javascript theme={null}
Schema.object({
  name:    Schema.string().required(),
  score:   Schema.number().min(0).max(100),
  tags:    Schema.array().items(Schema.string()),
  address: Schema.object({
    city:    Schema.string().required(),
    zip:     Schema.string().pattern(/^\d{5}$/),
  }),
})
```

Unknown keys are **automatically stripped** — only keys in the schema are kept in `result.value`. This prevents users from injecting unexpected fields.

#### Dynamic keys

For objects where keys are not known ahead of time, use `.pattern_values()`:

```javascript theme={null}
Schema.object({}).pattern_values(Schema.string().max(500))
```

This validates that every value in the object (regardless of key name) matches the rule.

### `Schema.any()`

Accepts any type. Useful with `.required()` or `.valid()`.

```javascript theme={null}
Schema.any().required()
Schema.any().valid('draft', 'published', 42, true)
```

## Modifiers

| Method | Applies to | Description |
| - | - | - |
| `.required()` | all | Value must be present (not `null`, `undefined`, or `""`) |
| `.optional()` | all | Value can be absent (this is the default) |
| `.default(val)` | all | Use this value when input is missing |
| `.label(name)` | all | Custom name in error messages |
| `.valid(a, b, …)` | all | Must be one of the listed values |
| `.min(n)` | string, number, array | Minimum length / value / item count |
| `.max(n)` | string, number, array | Maximum length / value / item count |
| `.email()` | string | Must be a valid email address |
| `.url()` | string | Must be an http/https URL |
| `.pattern(regex)` | string | Must match the regex |
| `.lowercase()` | string | Must be all lowercase |
| `.integer()` | number | Must be a whole number |
| `.positive()` | number | Must be > 0 |
| `.negative()` | number | Must be \< 0 |
| `.items(rule)` | array | Validate each array element |
| `.pattern_values(rule)` | object | Validate values of unknown keys |
| `.strip()` | all | Include in validation but exclude from output |
| `.custom(fn)` | all | Custom validator function (return error string or nothing) |

## Type coercion

The validator automatically coerces compatible types:

| Input | Schema | Result |
| - | - | - |
| `"42"` | `Schema.number()` | `42` |
| `"3.14"` | `Schema.number()` | `3.14` |
| `"true"` | `Schema.boolean()` | `true` |
| `"false"` | `Schema.boolean()` | `false` |
| `"1"` | `Schema.boolean()` | `true` |
| `"0"` | `Schema.boolean()` | `false` |

Non-coercible values fail validation (e.g. `"hello"` for `Schema.number()`).

## Custom validators

Use `.custom()` for logic that built-in methods don't cover:

```javascript theme={null}
var schema = Schema.object({
  start_date: Schema.string().required().custom(function (v, label) {
    if (isNaN(Date.parse(v))) return label + ' must be a valid date';
  }),
  password: Schema.string().required().min(8).custom(function (v, label) {
    if (!/[A-Z]/.test(v)) return label + ' must contain an uppercase letter';
    if (!/[0-9]/.test(v)) return label + ' must contain a digit';
  }),
});
```

The function receives `(value, label)` and should return an error string if validation fails, or nothing/undefined if it passes.

## Full POST example

A page at `/api/submit-checkin` that validates and stores data:

```html theme={null}
<script scope="backend">
if (request.method === 'POST') {
  var schema = Schema.object({
    weight:  Schema.number().required().min(50).max(500),
    unit:    Schema.string().valid('lbs', 'kg').default('lbs'),
    meal:    Schema.string().valid('breakfast', 'lunch', 'dinner', 'snack').required(),
    notes:   Schema.string().max(500).default(''),
  });

  var result = schema.validate(request.body);

  if (!result.valid) {
    response.status(400);
    response.json({ ok: false, errors: result.errors });
  }

  if (!is_customer) {
    response.status(401);
    response.json({ ok: false, errors: ['Not authenticated'] });
  }

  var data = result.value;

  setCrmField({ slug: 'my-entity-slug', fieldKey: 'current_weight', value: data.weight });
  setCrmField({ slug: 'my-entity-slug', fieldKey: 'last_meal', value: data.meal });
  setCrmField({ slug: 'my-entity-slug', fieldKey: 'last_checkin', value: new Date().toISOString() });

  response.json({ ok: true, data: data });
}
</script>
```

Frontend:

```javascript theme={null}
var res = await fetch('/api/submit-checkin', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    weight: 182.5,
    unit: 'lbs',
    meal: 'lunch',
  }),
});
var json = await res.json();
if (!json.ok) {
  console.error('Validation errors:', json.errors);
}
```

## Nested object example

```javascript theme={null}
var schema = Schema.object({
  user: Schema.object({
    first_name: Schema.string().required().max(100),
    last_name:  Schema.string().required().max(100),
    email:      Schema.string().required().email(),
  }).required(),
  preferences: Schema.object({
    notifications: Schema.boolean().default(true),
    theme:         Schema.string().valid('light', 'dark').default('light'),
  }).default({}),
  tags: Schema.array().items(Schema.string().max(50)).max(20).default([]),
});

var result = schema.validate(request.body);
// result.value.user.email is guaranteed to be a valid email string
// result.value.preferences.theme is guaranteed to be 'light' or 'dark'
// Any extra keys not in the schema are stripped
```

<Warning>
  **Always validate before storing.** Even though the Schema library strips unknown keys and enforces types, it's a good practice to apply `.max()` constraints on strings and arrays to prevent large payloads from consuming CRM storage.
</Warning>


# Directives
Source: https://docs.elasticfunnels.io/backend-template-engine/directives

Backend template directives: @if, @else, @foreach, @set, session storage, @component, @extends, @block.

This page describes the **directives** the backend template engine understands. Use them in the page builder via the corresponding **backend** blocks, or write them directly in coded templates.

## Conditionals: `@if`, `@else`, `@elseif`, `@endif`

Show one block when a condition is true, optionally with else branches.

```html theme={null}
@if(article)
  <h1>{{ article.title }}</h1>
@else
  <p>Article not found.</p>
@endif
```

* **`@if(condition)`** — Renders the following content only when the condition is truthy.
* **`@else`** — Optional; rendered when the `@if` condition is false.
* **`@elseif(condition)`** — Optional; additional condition; first matching branch is used.
* **`@endif`** — Ends the conditional block.

### Conditions

You can use:

* **Word operators** (safe in HTML): `eq`, `neq`, `lt`, `lte`, `gt`, `gte`\
  Example: `@if(orders.length gt 0)`
* **Symbols** (where allowed): `===`, `!==`, `==`, `!=`, `<=`, `>=`, `<`, `>`
* **Logic:** `and`, `or`, unary `!`
* **Property checks:** `@if(article.author_avatar)`, `@if(related_articles && related_articles.length)`

Example with `@elseif` and array length:

```html theme={null}
@if(posts && posts.length)
  @foreach(post in posts)
    <article>…</article>
  @endforeach
@else
  <p>No posts yet.</p>
@endif
```

***

## Loops: `@foreach` … `@endforeach`

Repeat a block once per element in an array.

```html theme={null}
@foreach(post in posts)
  <article>
    <h3><a href="{{ post.details_url }}">{{ post.title }}</a></h3>
    <p>{{ post.excerpt | default:post.summary | default:'' | raw }}</p>
  </article>
@endforeach
```

* **`@foreach(item in array)`** — `item` is the variable name for the current element; `array` is an expression that must evaluate to an array (e.g. `posts`, `related_articles`).
* **`@endforeach`** — Required; ends the loop.
* **`@each(item in array)` … `@endeach`** — Same loop under another name; either closer works.
* **`@foreach((key, value) in object)`** — Loop over an object's keys and values.

Inside the block you can use `{{ item.property }}`, `@if`, nested `@foreach`, and filters.

### The `loop` variable

Inside every loop, `loop` describes the current pass:

| Property | Value |
| - | - |
| `loop.index` | Position, counting from **0** |
| `loop.iteration` | Position, counting from **1** |
| `loop.first` / `loop.last` | `true` on the first / last pass |
| `loop.count` | Number of items |
| `loop.remaining` | Items still to come after this one |
| `loop.even` / `loop.odd` | Based on `loop.iteration` |
| `loop.depth` | `1` for an outer loop, `2` inside it, and so on |
| `loop.parent` | The enclosing loop's `loop`, in a nested loop |

For example, an `ItemList` with a position and no trailing comma:

```html theme={null}
<script type="application/ld+json">
{"@context":"https://schema.org","@type":"ItemList","itemListElement":[@foreach(post in posts){"@type":"ListItem","position":{{ loop.iteration }},"url":"{{ post.url }}"}@if(!loop.last),@endif@endforeach]}
</script>
```

`loop`, like the item variable, exists only inside the loop.

### Variables set inside a loop

A variable you `@set` inside a loop keeps its value after `@endforeach`, and each pass sees the value the previous pass left. Use it for counts and totals:

```html theme={null}
@set(shown = 0)
@set(total = 0)
@foreach(product in products)
  @set(shown = shown + 1)
  @set(total = total + product.price)
@endforeach
<p>{{ shown }} products, {{ total }} in total</p>
```

Because the value carries over, reset a per-item variable at the top of the loop body when only some items set it:

```html theme={null}
@foreach(product in products)
  @set(badge = '')
  @if(product.on_sale)@set(badge = 'Sale')@endif
  <span>{{ badge }}</span>
@endforeach
```

***

## Variables: `@set`

Define a variable for use later in the template.

```html theme={null}
@set(greeting = "Hello")
<p>{{ greeting }}, {{ name }}!</p>
```

Use when you need a reusable value or a clearer expression.

To put a quote of the same kind inside a string, escape it with a backslash, or use the other kind of quote around it:

```html theme={null}
@set(title = "He said \"hi\"")
@set(title = 'It\'s here')
@set(title = 'The "best" plan')
```

***

## Directives on one line

Directives work on a line of their own or inline, next to other directives and text. These two are the same:

```html theme={null}
@if(lang eq 'en')@set(show_banner = 'yes')@endif

@if(lang eq 'en')
@set(show_banner = 'yes')
@endif
```

Inline you can use `@if(` `@elseif(` `@else` `@endif`, `@foreach(` `@endforeach`, `@each(` `@endeach`, `@set(`, `@setSessionItem(` `@clearSessionItem(`, `@component(` and `@yield(`:

```html theme={null}
<ul>@foreach(item in items)<li>@if(loop.first)<b>{{ item }}</b>@else{{ item }}@endif</li>@endforeach</ul>
<a class="btn@if(active) btn--active@endif" href="/">Home</a>
```

Two directives need their own line:

* **`@extends(…)`** — On its own line, at the top of the file.
* **`@block(…)`** — On its own line, directly after a tag (`</style> @block("head")`), or with its `@endblock` on the same line (`<title>@block("title")About@endblock</title>`).

In any other position they are printed as text, and `ef lint` warns about it.

An `@` that doesn't start one of these directives is left as it is, so emails (`support@example.com`), handles (`@yourbrand`), CSS at-rules (`@media`, `@font-face`, `@import`) and `@` in scripts need no escaping. A word such as `@settings` or `use @set to` is text too: a directive needs its `(`.

***

## Components: `@component`

Include a reusable component by name, with optional arguments.

```html theme={null}
@component("header", { title: "Home" })
```

The engine looks up the component by name and renders it with the given arguments in context.

***

## Inheritance: `@extends`, `@block`, and `@yield`

Use a **base template** and override only certain regions.

`@yield("name")` and `@block("name")…@endblock` both define named regions in a base layout that child templates can fill. The difference: `@yield` has no default content (renders empty if not overridden), while `@block` can include default content as a fallback.

### Base template (e.g. layout)

The base defines named **blocks** that child templates can override:

```html theme={null}
<!DOCTYPE html>
<html>
<head><title>Site</title></head>
<body>
  @block("content")
    Default content here.
  @endblock
</body>
</html>
```

### Child template

The child declares which base it extends and redefines one or more blocks:

```html theme={null}
@extends("layout")
@block("content")
<main>
  <h1>{{ article.title }}</h1>
  {{ article.body | raw }}
</main>
@endblock
```

* **`@extends("pageSlug")`** — Must be at the top; use the base page’s slug.
* **`@block("name")` … `@endblock`** in the child — Replaces the same-named `@block` or `@yield` in the base. Only the blocks you define are overridden; the rest of the base layout is used as-is.

### `@yield` vs `@block` — when to use which

`@yield("name")` is a slot with **no default content** — nothing renders if the child does not provide an override. `@block("name") default @endblock` has **optional default content** that renders when no child override is provided.

| | `@block("name") default @endblock` | `@yield("name")` |
| - | - | - |
| Default content | Yes — rendered when child doesn't override | No — renders empty |
| Typical use | Optional sections (header, sidebar, scripts) | Required slots (title, main content, page-level style) |

Example base layout using `@yield` for required slots and `@block` for optional ones:

```html theme={null}
<head>
  <title>@yield("title") · My Site</title>
  <style>@yield("style")</style>
</head>
<body>
  @block("header")<header><a href="/">Home</a></header>@endblock
  <main>@yield("content")</main>
  @block("scripts")@endblock
</body>
```

Child template:

```html theme={null}
@extends("layout")
@block("title")About@endblock
@block("style").about { padding: 80px 0; }@endblock
@block("content")<h1>About us</h1>@endblock
```

In the **page builder**, inheritance is supported with a read-only base layer: only the block regions are editable, and on save only the child source (extends + blocks) is stored.

***

## Session storage

You can store and read simple values in the visitor’s session from templates. Use this for things like remembering a choice across requests (e.g. a selected option, a flag) without using the frontend.

| Call | Purpose |
| - | - |
| **`@setSessionItem('key', value)`** | Store a value in the session. Use **`@setSessionItem('key', null)`** to clear that key. |
| **`{{ getSessionItem('key') }}`** | Output the stored value, or empty if not set. |
| **`@clearSessionItem('key')`** | Remove the key from the session (same as setting it to null). |

**Rules:**

* **Keys** may only use letters, numbers, and underscores (`a–z`, `A–Z`, `0–9`, `_`). Other characters are stripped.
* **Values** are stored safely (encoded). You can pass strings or numbers; other types are JSON-serialized. There is a size limit per value (\~64 KB).
* **Clearing:** Passing `null` (or nothing) to `setSessionItem` removes the key, as does `@clearSessionItem('key')`.

**Session length and when it resets**

* **Lifetime:** Session data (including values you store with `setSessionItem`) lasts **3 hours** from when the session was first created. The timer does **not** reset on each page load—so after 3 hours the session expires and all stored values are gone.
* **When it resets:** The session is tied to the visitor’s session cookie. It is cleared when:
  * the 3-hour lifetime has passed,
  * the visitor clears their cookies,
  * or they use a different browser or device (new session).
* Use session storage for short-lived, per-visit state (e.g. “has seen this step”, “selected option for this visit”). For long-lived or cross-device data, use a different mechanism (e.g. customer account, database).

**Examples:**

```html theme={null}
@setSessionItem('selected_plan', 'premium')
<p>You chose: {{ getSessionItem('selected_plan') }}</p>
```

```html theme={null}
@if(getSessionItem('seen_intro'))
  <p>Welcome back.</p>
@else
  @setSessionItem('seen_intro', '1')
  <p>First time here? Read this…</p>
@endif
```

```html theme={null}
@clearSessionItem('cart_note')
@setSessionItem('cart_note', null)
```

***

## Summary

| Directive | Purpose |
| - | - |
| `@if(condition)` … `@endif` | Conditional block |
| `@else` / `@elseif(condition)` | Else branches |
| `@foreach(item in array)` … `@endforeach` | Loop (`@each` … `@endeach` is the same) |
| `loop.index` / `loop.iteration` / `loop.first` / `loop.last` | Position inside a loop |
| `@set(variable = expression)` | Set variable |
| `@setSessionItem('key', value)` | Store (or clear with null) session value |
| `{{ getSessionItem('key') }}` | Output session value |
| `@clearSessionItem('key')` | Remove session value |
| `@component("name", args)` | Include component |
| `@extends("pageSlug")` | Extend base template |
| `@block("name")` … `@endblock` | Define/override block |

Next: [Variables and filters](/backend-template-engine/variables-and-filters).


# Overview
Source: https://docs.elasticfunnels.io/backend-template-engine/overview

Introduction to the backend template engine: server-side directives and variable interpolation.

The **Backend Template Engine** renders templates on the server (or in preview) using directives like `@if`, `@foreach`, and `{{ variable }}`. The output is plain HTML sent to the visitor. Use it for content that is fixed at request time, such as product lists, blog posts, conditional sections, or layout structure that does not change after the page loads.

<Note>
  Use **`{{ }}`** for backend (server-side) variables. Use **`[[ ]]`** for frontend (client-side) values that update in the browser. Both can appear on the same page. For live-updating content (cart, totals, conditional UI), see [Frontend Template Engine](/frontend-template-engine/overview).
</Note>

<Warning>
  This engine runs **last** on the server — after the page-events graph has already filled every split-test and dynamic container. An `@if` wrapped around a container therefore hides the result but does **not** prevent the container from being filled (or the visitor from being enrolled in the test). See [Rendering pipeline](/pages/rendering-pipeline) for the full order.
</Warning>

## When to use it

Use the backend template engine when:

* **Content is fixed at request time** - Blog posts, product details, category lists, or any data that does not change while the visitor is on the page.
* **You need conditionals or loops in the HTML** — Show or hide blocks with `@if` / `@else`, or repeat a block per item with `@foreach`.
* **You use layout inheritance** — A base layout with `@extends` and `@block` so child pages only define the changing regions.

If the content depends on the visitor and must update without reloading (e.g. cart items, totals, coupon status), use the [Frontend Template Engine](/frontend-template-engine/overview) instead.

## Page builder vs coded templates

| Context | How you work | What gets saved / rendered |
| - | - | - |
| **Page builder (GrapeJS)** | Drag **backend** blocks from the Template Engine category: “If (Backend)”, “Else (Backend)”, “Foreach (Backend)”, “Extends (Backend)”, “Block (Backend)”, etc. | The builder saves `@if(...)`, `@else`, `@foreach(...)`, `@extends(...)`, `@block(...)` in the page HTML. The backend engine renders these when the page is built or previewed. |
| **Coded / hand-written templates** | Write the same directives directly in the template source. | No extra tags; the engine reads `@if`, `@foreach`, `{{ ... }}`, and so on. |

So:

* **In the page builder:** Use the **backend** blocks (If, Else, Foreach, Set, Component, Extends, Block) so the correct `@…` directives are emitted.
* **In coded templates:** Use **`@if`**, **`@else`**, **`@foreach`**, **`{{ }}`**, **`@set`**, **`@component`**, **`@extends`**, **`@block`** directly.

## What the engine provides

| Feature | Purpose |
| - | - |
| **`{{ path }}`** | Insert a value from the current context (variables, properties). |
| **`{{ path \| filter }}`** | Apply a filter (e.g. `default`, `upper`, `slice`, `raw`). |
| **`{{ "text" + path }}`** | Concatenate strings and values with `+`. |
| **`@if(condition)` … `@endif`** | Show a block only when the condition is true. |
| **`@else`** / **`@elseif(condition)`** | Optional branches inside an `@if`. |
| **`@foreach(item in array)` … `@endforeach`** | Repeat a block once per item. |
| **`@set(name = value)`** | Set a variable for the rest of the template. |
| **`@setSessionItem('key', value)`** / **`getSessionItem('key')`** / **`@clearSessionItem('key')`** | Store, read, or clear a value in the visitor’s session. |
| **`@component("name", args)`** | Include a reusable component. |
| **`@extends("pageSlug")`** | Use a base template; override with `@block`. |
| **`@block("name")` … `@endblock`** | Define or override a named region in the layout. |

Details and examples are in [Directives](/backend-template-engine/directives), [Variables and filters](/backend-template-engine/variables-and-filters), and [Products, categories & shipping](/backend-template-engine/products-and-shipping) (catalog and shipping profile functions).

## Relation to other docs

* **Frontend Template Engine** — [Overview](/frontend-template-engine/overview), [Syntax](/frontend-template-engine/syntax): client-side `[[ ]]`, `<template-if>`, `<template-foreach>`, etc.
* **Backend Template Engine** (this section) — Server-side `{{ }}`, `@if`, `@foreach`, filters, inheritance.

Next: [Directives](/backend-template-engine/directives).


# Products, categories & shipping (backend)
Source: https://docs.elasticfunnels.io/backend-template-engine/products-and-shipping

Backend template functions for catalog data: products, product categories, shipping profiles, and tax-related hints.

These functions load **your brand’s** product catalog and shipping configuration. They are available in **backend** templates (server-rendered `{{ }}` and `@foreach`, etc.). All data is **scoped to the current brand** automatically—the page’s brand context supplies the brand id, and the platform never mixes another brand’s products or profiles into your page.

<Note>
  If the brand context is missing or invalid, these functions return **empty results** or **`null`** (they do not fall back to a global list). Category joins also require category rows to belong to the **same brand** as the product.
</Note>

## Product lookups

| Function | What it returns |
| - | - |
| **`getProduct(code)`** | One product by **code** or numeric **id** (for the current brand). |
| **`getProduct(brandId, code)`** | Same, but the first argument is an explicit brand id (advanced; still validated). |
| **`getAllProducts()`** | Every product for the brand, storefront visibility ignored (cached on the server for performance). |
| **`getProducts(filters)`** | Filtered list, **listable products only** by default. Optional object `filters`: `type`, `classification`, `codes`, **`category_id`**, **`subcategory_id`**, **`show_in_frontend`** (see below). |
| **`getProductByCode(brandId, merchantCode, productCode)`** | Resolve a product by merchant integration code (advanced). |

<Note>
  These names are also available in **PascalCase** (`GetProducts`, `GetProduct` and so on). Both spellings call the same function, so pages written against the old names keep working. Use camelCase in new pages, which is what backend scripts and most other template functions already use.
</Note>

### Storefront visibility

Each product has a **Show in frontend** toggle (Products, open the product, **General**). It is **on by default**.

**`getProducts()` returns only products with it on.** Your product table is not the same thing as your catalog: it also holds upsell-only SKUs, order bumps, bonuses and funnel-specific variants that were never meant to be browsed. Turning the toggle off keeps a product out of shop and category listings without touching anything else.

| You want | Pass |
| - | - |
| Only listable products (**default**) | nothing, or `{ show_in_frontend: true }` |
| Everything, hidden included | `{ show_in_frontend: 'any' }` |
| Only the hidden ones | `{ show_in_frontend: false }` |

```html theme={null}
@foreach(p in getProducts())
  <p>{{ p.title }}</p>
@endforeach

@foreach(p in getProducts({ show_in_frontend: 'any' }))
  <p>{{ p.title }} - listed: {{ p.show_in_frontend }}</p>
@endforeach
```

<Warning>
  **Hidden is not the same as unavailable.** A hidden product still resolves through `getProduct(code)`, still prices, still checks out and still fulfils, so every funnel that sells it keeps working. Use **Status: Archived** when you want to stop selling a product.
</Warning>

`getAllProducts()` is deliberately **not** filtered. It is the literal everything list, which is what member areas and order pages need to resolve a product a customer has already bought, even after you have taken it off the shop.

The flag also travels on the product object as **`show_in_frontend`** (boolean), so you can branch on it yourself.

### Fields you can use on a product

Typical fields include **code**, **title**, **checkout\_title**, **slug**, **price**, **retail\_price**, **currency**, **image**, **description**, **classification**, **tax\_category** (tax provider code), **tax\_exempt**, subscription fields when applicable, downloadable files, and merchandising categories:

* **`title`** — The customer-facing display title: uses **checkout\_title** when set, otherwise the internal title.
* **`slug`** — SEO-friendly URL slug. Auto-generated from checkout\_title/title if not manually set in the SEO tab. Used with [wildcard routes](/pages/wildcard-routes) for clean product URLs (e.g. `{{ product | productUrl:'shop/product' }}` → `/shop/product/my-product-123`).
* **`product_category_id`** / **`product_subcategory_id`** — ids in your **product category** tree (configured in the Products area).
* **`category_name`** / **`subcategory_name`** — display names for those ids (when set on the product).
* **`product_files`** — downloadable files attached to the product. Each row includes **`purpose`** (`digital` or `bonus`), **`title`**, **`description`**, **`image`**, **`file`**, **`kind`** (one of `'audio'`, `'video'`, `'document'`, `'image'`, `'archive'`, `'file'` — derived from extension/mime so you don't have to classify yourself), **`is_primary`**, **`sort_order`**, and **`metadata`** (`mime_type`, `size`, `checksum`, `extension`).
* **`bonus_files`** / **`digital_files`** — purpose-filtered views of `product_files`.
* **`primary_download_url`** — convenience URL for the product’s first primary downloadable file.

Use **`productDownloads(product)`** when you want a single rolled-up array of everything the customer can download — `digital_files` then `bonus_files` then anything else in `product_files`, with the legacy `digital_file` / `bonus_file` scalars filled in only when no file rows exist, deduplicated by URL. Each entry: `{ url, title, kind, purpose, extension, mime_type, size, is_primary, sort_order }`.

Use **`getProducts`** with **`category_id`** to limit to products in that category or subcategory row (matches either primary or subcategory assignment). Use **`subcategory_id`** to require a specific subcategory id on the product.

### Display helpers

| Function / filter | Purpose |
| - | - |
| **`productSavings(product)`** | Object with savings **amount**, **percent**, and formatted strings for marketing copy. |
| **`subscriptionSummary(product)`** | Short human-readable subscription line (trial, billing interval). |
| **`productDownloads(product)`** | Flat, deduplicated array of every downloadable file for the product. Each entry: `{ url, title, kind, purpose, extension, mime_type, size, is_primary, sort_order }`. `kind` is one of `'audio'`, `'video'`, `'document'`, `'image'`, `'archive'`, `'file'`. |
| **`formatPrice`** filter | Format a number with currency (e.g. `{{ product.price \| formatPrice:product.currency }}`). |
| **`savings`**, **`compareAt`**, **`pricePerUnit`**, **`subscriptionLabel`**, **`merchantPriceId`** filters | Convenience formatting on a product object. |
| **`productUrl`** filter | SEO-friendly product URL: `{{ product \| productUrl:'shop/product' }}` → `/shop/product/{slug}-{id}`. Use with [wildcard routes](/pages/wildcard-routes) for product detail pages. |

## Product categories

| Function | What it returns |
| - | - |
| **`getProductCategories()`** | Default: full category **tree** in order, each item includes **`depth`** (0 = top level). |
| **`getProductCategories({ parent_id: N })`** | Direct **children** of category `N` only (flat list, sorted). |
| **`getProductCategories({ tree: false })`** or **`{ flat: true }`** | Flat list of all categories (no `depth`). |
| **`getProductCategories({ top_level: true })`** | Only categories with no parent (then tree or flat as above). |

Combine with **`@foreach`** to build category navigation or filter UI on landing pages.

## Shipping profiles

Shipping profiles define **rates and rules** used at checkout. These functions help you build **shipping policy** or **FAQ** pages.

| Function | What it returns |
| - | - |
| **`getShippingProfiles()`** | All shipping profiles for the brand. **`shipping_costs`** is a **parsed object** (e.g. regional keys, `default`, `overrides`). **`has_shipping_rates`** is true when that object has keys. |
| **`getShippingProfiles({ selectable_only: true })`** | Only profiles visitors can pick at checkout (when that option is enabled on the profile). |
| **`getShippingProfiles({ include_product_stats: true })`** | Same as list mode, but each row also includes **`products_count`** and **`tax_categories`**. Use only when you need counts or tax-code summaries—extra queries run per profile. |
| **`getShippingProfile(profileId)`** | One profile by id, **including** product stats (**`products_count`**, **`tax_categories`**). |
| **`getDefaultShippingProfile()`** | The profile marked default, with the same enrichment as a single **`getShippingProfile`**. |

### `tax_categories` on a shipping profile

Shipping profiles do **not** store a tax code themselves. **`tax_categories`** is the list of **distinct `tax_category` values** from **products** that use that shipping profile—useful for disclosure text (“products shipped under this method may use tax codes …”), not for live tax calculation (checkout handles that).

### Other useful fields

* **`name`**, **`description`**
* **`is_default`**, **`allow_select_on_checkout`**
* **`product_stats_loaded`** — `false` on list responses unless you set **`include_product_stats: true`**

## Examples

**List products in a category** (replace `3` with a real category id from your store):

```html theme={null}
@foreach(p in getProducts({ category_id: 3 }))
  <p>{{ p.title }} — {{ p.price | formatPrice:p.currency }}</p>
@endforeach
```

**Category menu (tree):**

```html theme={null}
@foreach(c in getProductCategories())
  <p style="padding-left: {{ c.depth * 12 }}px">{{ c.name }}</p>
@endforeach
```

**List a product's downloads with type-aware icons** (no URL parsing required):

```html theme={null}
@foreach(file in productDownloads(getProduct('my-sku')))
  <a href="{{ file.url }}" target="_blank">
    @if(file.kind eq 'audio')🎧
    @elseif(file.kind eq 'video')🎬
    @elseif(file.kind eq 'document')📄
    @elseif(file.kind eq 'image')🖼️
    @elseif(file.kind eq 'archive')📦
    @else📁
    @endif
    {{ file.title }} ({{ file.extension }})
  </a>
@endforeach
```

**Shipping methods (names only, fast):**

```html theme={null}
@foreach(s in getShippingProfiles())
  <li>{{ s.name }}@if(s.is_default) (default)@endif</li>
@endforeach
```

## See also

* [Backend Template Engine overview](/backend-template-engine/overview)
* [Directives](/backend-template-engine/directives)
* [Variables and filters](/backend-template-engine/variables-and-filters)
* Product links and checkout: [Buy links](/products/buy-links), [Cart page tag](/pages/cart)


# Variables and filters
Source: https://docs.elasticfunnels.io/backend-template-engine/variables-and-filters

Backend template variables {{ path }} and filters: default, slice, raw, t (translations), upper, lower, truncate, replace, currency, join, and more.

Backend templates insert values with **`{{ path }}`** and can transform them with **filters** using the pipe character: **`{{ path | filter }}`** or **`{{ path | filter:arg }}`**.

For `filter:arg`, the argument can be either:

* a **context path/expression** (for example `product.currency_code`)
* or a **literal** (recommended as quoted text, for example `'USD'` or `'stripe'`)

## Variables: `{{ path }}`

Values are resolved from the current context (e.g. page data, article, posts, featured).

| You write | Meaning |
| - | - |
| `{{ article.title }}` | Property of the current article |
| `{{ post.details_url }}` | URL for a post (e.g. in a loop) |
| `{{ featured[0].title }}` | First featured item's title |
| `{{ blog_base_url \| default:'/blog' }}` | URL with fallback |

Paths can use dot notation and array indexing. If a value is missing, it usually renders as empty unless you use the **`default`** filter.

***

## Filters

Filters are applied left to right. You can chain several: **`{{ value | filter1 | filter2:arg }}`**.

### Filter arguments (`:arg`)

Use `:arg` when a filter needs one parameter.

```html theme={null}
{{ product.price | currency:product.currency_code }}
{{ product.price | currency:'USD' }}
```

In the first example, `product.currency_code` is resolved from context (for example, `USD`).\
In the second example, `'USD'` is a fixed literal.

If you want text to always be treated as literal, quote it.

***

## Translation filter: `t`

For [brand translations](/pages/internationalization), **`| t`** treats the piped value as a **translation key** string. Resolution matches **`t()`**: brand dictionary for the resolved locale first, then built-in locale strings. Optional **`| t:params`** passes a context variable or safe expression that resolves to a **plain object** for built-in placeholder interpolation (same rules as **`t(key, params)`**).

```html theme={null}
{{ 'hero.title' | t }}
{{ t('hero.title') }}
{{ 'product.savings_percent' | t:savingsOpts }}
```

Use **`t()`** and **`| t`** in templates for the same resolution order (brand first, then built-in). See [Internationalization (i18n)](/pages/internationalization) for **`locales()`**, **`{{ locale }}`**, and backend **`await t()`**.

***

## Fallback filters

### `default` — fallback when value is empty

If the value is empty (null, undefined, or empty string), the filter returns the argument instead.

```html theme={null}
{{ article.date_short | default:article.published_at | default:article.created_at }}
```

Chain multiple fallbacks — the first non-empty value wins.

```html theme={null}
{{ article.author_name | default:'Author' }}
{{ article.reading_time | default:'5' }} min read
```

### `default_if_none` — fallback only for null/undefined

Like `default`, but only triggers when the value is `null` or `undefined`. An **empty string** passes through unchanged.

```html theme={null}
{{ score | default_if_none:'0' }}
```

***

## String filters

### `upper` / `lower` / `capitalize` / `title`

```html theme={null}
{{ customer.first_name | upper }}       <!-- JOHN -->
{{ customer.first_name | lower }}       <!-- john -->
{{ customer.first_name | capitalize }}  <!-- John -->
{{ product.name | title }}              <!-- My Product Name -->
```

### `trim`

Strip leading and trailing whitespace.

```html theme={null}
{{ var.label | trim }}
```

### `first` / `last`

Return the first or last character of a string (or first/last element of an array).

```html theme={null}
{{ customer.first_name | default:'A' | upper | first }}  <!-- initial letter -->
{{ items | last }}
```

### `slice` — substring

Use **`slice:start:end`** (e.g. `slice:0:1` for the first character, `slice:0:3` for the first 3).

```html theme={null}
{{ (article.author_name | default:'A') | slice:0:1 }}
```

Parentheses ensure the whole expression is evaluated first, then `slice` is applied to the result.

### `replace` — find and replace

Replace all occurrences of a substring. Arg format: `'old':'new'`. Plain string replacement — no regex.

```html theme={null}
{{ product.sku | replace:'-':' ' }}
{{ phone | replace:'(':'') | replace:')':'' | replace:' ':'' }}
```

### `truncate` — limit character length

Truncate to N characters, appending `...` if the value was cut.

```html theme={null}
{{ article.excerpt | truncate:160 }}
```

### `truncatewords` — limit word count

Truncate to N words, appending `...` if cut.

```html theme={null}
{{ article.body | truncatewords:30 }}
```

### `nl2br` — newlines to `<br>`

Convert newline characters to `<br>` tags. The value is HTML-escaped first, so user content is safe. Chain with `| raw` to render the output as HTML.

```html theme={null}
{{ customer.notes | nl2br | raw }}
```

### `strip_tags` — remove HTML tags

Strip all HTML tags from a string. Useful for getting plain text from rich content.

```html theme={null}
{{ article.body | strip_tags | truncate:200 }}
```

### `url_encode` — percent-encode for URLs

Encode a value for safe use in a URL query string.

```html theme={null}
<a href="/search?q={{ query | url_encode }}">Search</a>
```

### `length` / `size`

Return the number of characters in a string, or the number of elements in an array. `size` is an alias.

```html theme={null}
{{ customer.bio | length }}
{{ order.items | size }}
```

***

## Number filters

### `round`

Round to the nearest integer, or to N decimal places.

```html theme={null}
{{ price | round }}       <!-- 42 -->
{{ price | round:2 }}     <!-- 41.99 -->
```

### `floor` / `ceil`

Round down or up to the nearest integer.

```html theme={null}
{{ price | floor }}
{{ price | ceil }}
```

### `abs`

Absolute value.

```html theme={null}
{{ order.balance | abs }}
```

### `number_format`

Format a number with thousands separator and fixed decimal places (default 2).

```html theme={null}
{{ revenue | number_format }}     <!-- 1,234.56 -->
{{ count | number_format:0 }}     <!-- 1,235 -->
```

### `currency`

Format a number as currency. Optional arg is the ISO 4217 currency code (default `USD`).

```html theme={null}
{{ price | currency }}          <!-- $1,234.56 -->
{{ price | currency:'EUR' }}    <!-- €1,234.56 -->
{{ price | currency:order.currency_code }}
```

***

## Boolean / conditional filters

### `yesno`

Return a string based on whether the value is truthy or falsy. Arg format: `'yes':'no'` or `'yes':'no':'maybe'` (the third value is used for `null`/`undefined`).

```html theme={null}
{{ order.active | yesno:'Active':'Inactive' }}
{{ member.verified | yesno:'✓':'✗' }}
{{ score | yesno:'Pass':'Fail':'No score yet' }}
```

***

## Array filters

### `join`

Join an array into a string with a separator.

```html theme={null}
{{ tags | join:', ' }}
{{ order.skus | join:' | ' }}
```

### `sort`

Sort an array alphabetically (strings) or numerically.

```html theme={null}
{{ categories | sort | join:', ' }}
```

### `reverse`

Reverse a string or array.

```html theme={null}
{{ items | reverse }}
{{ 'hello' | reverse }}  <!-- olleh -->
```

### `unique`

Remove duplicate values from an array.

```html theme={null}
{{ tags | unique | join:', ' }}
```

***

## Date filters

### `date` — format a date

Format a `Date` object, timestamp (ms), or the string `'now'` using format tokens.

| Token | Meaning | Example |
| - | - | - |
| `yyyy` | 4-digit year | 2024 |
| `yy` | 2-digit year | 24 |
| `MMMM` | Full month name | January |
| `MMM` | Short month name | Jan |
| `MM` | 2-digit month | 01 |
| `M` | Month (no padding) | 1 |
| `dd` | 2-digit day | 05 |
| `d` | Day (no padding) | 5 |
| `HH` / `H` | Hour 24h (padded / not) | 09 / 9 |
| `hh` / `h` | Hour 12h (padded / not) | 09 / 9 |
| `mm` / `m` | Minute (padded / not) | 04 / 4 |
| `ss` / `s` | Second (padded / not) | 07 / 7 |

```html theme={null}
{{ order.created_at | date:'MMM d, yyyy' }}    <!-- Jan 5, 2024 -->
{{ 'now' | date:'yyyy' }}                       <!-- current year -->
{{ order.created_at | date:'dd/MM/yyyy' }}
```

### `date_add` — add days to a date

Add N days to a date value. Returns a `Date` object — chain with `| date` to format.

```html theme={null}
{{ order.created_at | date_add:30 | date:'MMM d, yyyy' }}
{{ subscription.start_date | date_add:365 | date:'MMM d, yyyy' }}
```

Use a negative number to subtract days.

```html theme={null}
{{ 'now' | date_add:-7 | date:'MMM d, yyyy' }}   <!-- 7 days ago -->
```

### `timeago` — relative time

Render a date as a human-readable relative string.

```html theme={null}
{{ order.created_at | timeago }}       <!-- 3 days ago -->
{{ event.starts_at | timeago }}        <!-- in 2 hours -->
```

***

## Output / serialization filters

### `raw` — output HTML unescaped

By default, output is HTML-escaped for safety. Use **`raw`** only for trusted HTML (e.g. stored rich content like article body or excerpt).

```html theme={null}
{{ article.body | raw }}
{{ (post.excerpt | default:post.summary | default:'') | raw }}
{{ customer.notes | nl2br | raw }}
```

### `json` — serialize to JSON

Serialize any value to a JSON string. Safe: uses `JSON.stringify`, no code is executed. Chain with `| raw` to embed the output in HTML attributes or `<script>` tags without double-escaping.

```html theme={null}
<div data-config="{{ settings | json | raw }}"></div>
<script>var config = {{ settings | json | raw }};</script>
```

***

## Patterns from real templates

**Date with fallbacks:**

```html theme={null}
<span>{{ article.date_short | default:article.published_at | default:article.created_at }}</span>
```

**Avatar initial when no image:**

```html theme={null}
{{ (article.author_name | default:'A') | slice:0:1 }}
```

**Excerpt or summary, then output as HTML:**

```html theme={null}
{{ (featured[0].excerpt | default:featured[0].summary | default:'') | raw }}
```

**First initial from full name:**

```html theme={null}
{{ customer.first_name | default:'F' | upper | first }}
```

**Price formatted as currency:**

```html theme={null}
{{ product.price | currency:'USD' }}
```

**Trial end date:**

```html theme={null}
Your trial ends on {{ subscription.start_date | date_add:14 | date:'MMM d, yyyy' }}.
```

**Multi-line user notes:**

```html theme={null}
{{ customer.notes | nl2br | raw }}
```

**Embed data as JSON:**

```html theme={null}
<div data-product="{{ product | json | raw }}"></div>
```

**Optional category:**

```html theme={null}
@if(post.category)
  <span>{{ post.category.name }}</span>
@endif
```

***

## String concatenation: `+`

Use the **`+`** operator to join strings, variables, and filtered expressions together.

`+` works left to right as in JavaScript: two numbers are **added**, and as soon as a string is involved the values are **joined**. `{{ 1 + 2 }}` is `3`, `{{ "Order #" + 42 }}` is `Order #42`, and `{{ qty + extra + " items" }}` adds the two numbers first. A missing value joins as an empty string. That is what lets a loop keep a counter: `@set(n = n + 1)`.

```html theme={null}
{{ "(" + var.guarantee_title + ")" }}
```

You can combine it with filters by wrapping the filtered part in **parentheses**:

```html theme={null}
{{ "(" + (var.guarantee_title | default:"90-Day Money Back Guarantee") + ")" }}
```

This works everywhere expressions are accepted — in `{{ }}`, in `@set`, and in `@component` arguments:

```html theme={null}
@component("purchase-box", {
  title_suffix: "(" + (var.guarantee_title | default:"90-Day Guarantee") + ")"
})
```

```html theme={null}
@set(label = "Order #" + order.id)
{{ label }}
```

<Warning>
  Strings are **literal** — there is no variable interpolation inside quotes. Writing `"price is: {{ price }}"` outputs the text `price is: {{ price }}` verbatim, it does **not** resolve the variable. To mix text and variables, use concatenation:

  ```html theme={null}
  {{-- ✗ wrong — {{ }} inside a string is literal text, not a variable --}}
  {{ "price is: {{ price }}" }}

  {{-- ✓ correct — concatenate the string and the variable --}}
  {{ "price is: " + price }}
  ```
</Warning>

***

## Filter reference

| Filter | Category | Arg | Example |
| - | - | - | - |
| `default` | Fallback | `'fallback'` | `{{ name \| default:'Anonymous' }}` |
| `default_if_none` | Fallback | `'fallback'` | `{{ score \| default_if_none:'0' }}` |
| `upper` | String | — | `{{ name \| upper }}` |
| `lower` | String | — | `{{ name \| lower }}` |
| `capitalize` | String | — | `{{ name \| capitalize }}` |
| `title` | String | — | `{{ name \| title }}` |
| `trim` | String | — | `{{ label \| trim }}` |
| `first` | String/Array | — | `{{ name \| first }}` |
| `last` | String/Array | — | `{{ name \| last }}` |
| `slice` | String/Array | `start:end` | `{{ name \| slice:0:1 }}` |
| `replace` | String | `'old':'new'` | `{{ sku \| replace:'-':' ' }}` |
| `truncate` | String | `N` | `{{ text \| truncate:100 }}` |
| `truncatewords` | String | `N` | `{{ text \| truncatewords:20 }}` |
| `nl2br` | String | — | `{{ notes \| nl2br \| raw }}` |
| `strip_tags` | String | — | `{{ body \| strip_tags }}` |
| `url_encode` | String | — | `{{ query \| url_encode }}` |
| `length` / `size` | String/Array | — | `{{ items \| length }}` |
| `round` | Number | `decimals` | `{{ price \| round:2 }}` |
| `floor` | Number | — | `{{ price \| floor }}` |
| `ceil` | Number | — | `{{ price \| ceil }}` |
| `abs` | Number | — | `{{ balance \| abs }}` |
| `number_format` | Number | `decimals` | `{{ revenue \| number_format:2 }}` |
| `currency` | Number | `'USD'` | `{{ price \| currency:'USD' }}` |
| `yesno` | Boolean | `'yes':'no'` | `{{ active \| yesno:'Yes':'No' }}` |
| `join` | Array | `','` | `{{ tags \| join:', ' }}` |
| `sort` | Array | — | `{{ items \| sort }}` |
| `reverse` | String/Array | — | `{{ items \| reverse }}` |
| `unique` | Array | — | `{{ tags \| unique }}` |
| `date` | Date | `'format'` | `{{ date \| date:'MMM d, yyyy' }}` |
| `date_add` | Date | `N days` | `{{ date \| date_add:30 }}` |
| `timeago` | Date | — | `{{ date \| timeago }}` |
| `raw` | Output | — | `{{ html \| raw }}` |
| `json` | Output | — | `{{ obj \| json \| raw }}` |
| `t` | Translation | optional object | `{{ 'hero.title' \| t }}` |

***

## Summary

* Use **`{{ path }}`** to output a value; use **`| filter`** or **`| filter:arg`** to transform it.
* **Chained `default`** — `a | default:b | default:c` gives the first non-empty value.
* **`slice:0:1`** — First character; combine with `(expression | default:'X')` for safe initials.
* **`raw`** — Use only for trusted HTML (e.g. article body, nl2br output, json).
* **Parentheses** — `{{ (expression) | filter }}` so the filter applies to the whole expression.
* **Concatenation** — `"text" + variable + "more text"` joins values. No interpolation inside strings; use `+` instead.
* **`| t`** — Pipe a string key for translations; see [Internationalization](/pages/internationalization).

## Purchase Link Functions

These functions generate URLs for purchase and subscription actions. Use them in link `href` attributes.

| Function | Output | Description |
| - | - | - |
| `{{ upsell_upgrade('old_sku', 'new_sku') }}` | JS action URL | Upgrade subscription from one product to another |
| `{{ upsell_cancel() }}` | JS action URL | Cancel the current subscription |

These can also be used as filters: `{{ 'old_sku' | upsell_upgrade('new_sku') }}`.

See [Subscription Upsells](/products/subscription-upsells) for usage details and examples.

***

For conditionals and loops, see [Directives](/backend-template-engine/directives). For client-side templates, see [Frontend Template Engine](/frontend-template-engine/overview).


# Checkout functionality reference
Source: https://docs.elasticfunnels.io/checkouts/checkout-functionality-reference

Canonical reference for ElasticFunnels checkout: scope, fields, checkout_settings, abuse protection, submit flow, and redirects.

This page is the **source of truth** for how ElasticFunnels checkout works: configuration keys, server behavior, and what visitors experience.

For a **step-by-step page build** (HTML patterns, wizard layout, copy-paste examples), use [How to design a checkout page](/guides/how-to-design-a-checkout-page). That guide defers to this page for exact semantics of `checkout_settings` and security options.

For **template syntax** (`[[ ]]`, bindings, `checkout.*` in the page builder), see [Frontend Template Engine: Checkout](/frontend-template-engine/checkout).

***

## 1) Enable checkout on a page

Checkout behavior runs only when the page is marked as a checkout page:

1. Open **Page List** → **Edit Page**
2. Enable **Is checkout page**
3. Save

If this is off, `checkout` scope data, submit handling, payment processing, and post-purchase redirects may not run as documented here.

***

## 2) Checkout scope (frontend)

On checkout pages, the `checkout` scope is available to templates and bindings.

Common keys:

| Area | Keys |
| - | - |
| Customer | `checkout.customer.*` (names, email, phone, shipping/billing address fields) |
| Geography | `checkout.countries`, `checkout.usStates` (dropdown options) |
| Commerce | `checkout.coupon`, `checkout.coupon_message`, `checkout.bump_products`, `checkout.selectedBumpLines` |
| Totals | `checkout.subtotal`, `checkout.tax`, `checkout.shipping`, `checkout.total`, plus `*_raw` variants (see template engine doc) |
| Toggle | `checkout.shipping_same_as_billing` |
| Wallets | `checkout.wallet_available` (`{ applePay, googlePay }` — starts `false/false`, updated once Collect.js / Stripe.js detects support), `checkout.wallet_visible` (boolean — `true` once a wallet button actually renders; only promoted, never reset), `checkout.wallet_settings` (from `checkout_settings.wallet`) |
| Merchant | `checkout.merchant_country` (merchant's country, falling back to the domain's, then `US`) |
| Payment panel | `checkout.panel_billing_fields` (from `checkout_settings.billing_fields`; `null` = show all) |
| Subscription | `checkout.is_subscription`, `checkout.subscription.*` (see template engine doc for the full shape, including `intro_offer`, `price_steps`, `prepaid`, `tiers`) |

Template engine details: [Checkout](/frontend-template-engine/checkout).

<Warning>
  **`checkout.shipping` renders `$0.00` when the buyer's region has no rate defined.** Shipping comes from the product's shipping profile, and its **Mainland US** and **International** rates are independent - an empty rate is treated as free shipping for that region, not as a fallback to the other rate. A blank International Cost therefore ships free to every non-US buyer, and a product with no shipping profile ships free everywhere. See [How a shipping rate is chosen](/products/product-management).
</Warning>

***

## 3) Supported form field names

These align with what the checkout runtime validates and submits (shipping-first; billing can mirror shipping).

**Names**

Two name pairs exist and both are recognised:

* `shipping_first_name`, `shipping_last_name` — what the **Checkout Details** builder block emits, and what the server requires (with fallbacks). Use these on shipping-collecting pages.
* `first_name`, `last_name` — what `<checkout-personal-details>` emits, and the pair the card panel checks when deciding whether to inject its own "Cardholder Name" field.

<Note>
  The cardholder-name detector only looks for `first_name` / `last_name`. A page that collects `shipping_first_name` / `shipping_last_name` (the builder default) will therefore also get a **redundant** Cardholder Name field injected into the card panel. Add `first_name` / `last_name` inputs — hidden ones are fine — if you want to suppress it.
</Note>

Where a name is missing, the server backfills it: personal ← shipping ← billing ← the cardholder name (split into first / last).

**Shipping / personal**

* `email` (required), `phone` (optional)
* `shipping_address`, `shipping_address2` (optional)
* `shipping_country` (required, 2-letter, uppercased), `shipping_city`, `shipping_state`, `shipping_zip`

<Note>
  Client-side validation requires any of these that are **present on the page**; server-side, only `email`, `shipping_country` and the shipping name pair are strictly required — address, city, state and ZIP are accepted empty. `shipping_country` defaults to `US` when left blank.
</Note>

**Billing** (when shown; if empty, shipping values are used)

* `billing_first_name`, `billing_last_name` — never client-side required
* `billing_address`, `billing_address2`, `billing_country`, `billing_city`, `billing_state`, `billing_zip` — validated client-side only when a billing field is visible; all optional server-side

**Toggle**

* `shipping_same_as_billing` → `checkout.shipping_same_as_billing`

**Errors**

* Use `data-checkout-error="<field_name>"` matching the input `name` for inline validation messages.

***

## 4) `checkout_settings` (backend script)

Configure checkout using variables set in a **backend** script on the **same checkout page** (`<script scope="backend">`). The platform reads `checkout_settings` when the page is rendered.

```html theme={null}
<script scope="backend">
setVariable("checkout_settings", {
  // Optional: restrict countries / US states (see 4.1)
  // Optional: order bumps the page always offers (see 4.2)
  // Optional: checkout abuse protection (see section 5)
});
</script>
```

<Warning>
  **`setVariable` is what publishes the settings. A bare `var` does nothing.**

  Backend scripts run in a sandbox, and the only value that leaves it is what you hand to
  `setVariable`. Writing `var checkout_settings = {...}` and stopping there leaves the object
  inside the sandbox where nothing reads it. Nothing errors and the page renders normally, so the
  mistake is invisible: your country allowlist is silently not applied and your bumps never appear.

  If you would rather build the object up in steps, that is fine. Just publish it at the end:

  ```html theme={null}
  <script scope="backend">
  var checkout_settings = {};
  checkout_settings.countries = ['US'];
  setVariable("checkout_settings", checkout_settings);
  </script>
  ```
</Warning>

### 4.1 Countries and US states allowlist

Keys:

* `checkout_settings.countries` → drives `checkout.countries` in the UI
* `checkout_settings.usStates` → drives `checkout.usStates` for US state dropdowns

Allowed entry formats:

* Two-letter codes as strings: `'US'`, `'ca'`, `'tx'`
* `{ value: 'US' }`
* `{ value: 'US', label: 'United States' }`

Behavior:

1. Values are normalized (e.g. uppercase) and validated against built-in lists.
2. Invalid entries are dropped.
3. If nothing valid remains, the full default lists are used (not restricted).
4. The effective allowlist is stored in the visitor **session** and **re-validated on submit**, so blocked values cannot be forced with browser devtools alone.

Example, countries only:

```html theme={null}
<script scope="backend">
setVariable("checkout_settings", {
  countries: ['US', 'CA', 'GB']
});
</script>
```

Example, US states only:

```html theme={null}
<script scope="backend">
setVariable("checkout_settings", {
  usStates: ['CA', 'TX', 'NY', 'FL']
});
</script>
```

### 4.2 Order bumps the page always offers

`checkout_settings.bumps` names the order bumps this checkout page offers, so they do not depend
on the URL or on a funnel run. Each entry is a **bump product code**, or an object carrying
overrides:

```html theme={null}
<script scope="backend">
setVariable("checkout_settings", {
  countries: ['US'],
  bumps: ['bump-alzheimers-video']
});
</script>
```

```html theme={null}
<script scope="backend">
setVariable("checkout_settings", {
  bumps: [
    { code: 'bump-shipping-protection', description: 'Covers loss in transit', added_message: 'Protected' }
  ]
});
</script>
```

Behavior:

1. Each code is resolved against the product catalog. A product whose classification is not
   `bump` is skipped, so a typo shows nothing rather than selling the wrong item.
2. `name`, `price` and `image` always come from the product record. `description`,
   `image` and `added_message` given here override it when non-empty.
3. These merge with any bumps from `?bumps=` and from the **Set Checkout Bumps** node. A code
   declared in more than one place is offered once.

<Tip>
  Prefer this over the URL when a page should always carry the same bump. Because it lives on the
  page, it survives a direct hit, a refresh and a shared link, none of which is true of `?bumps=`.
  Use the **Set Checkout Bumps** node instead when the bump set is decided per funnel branch or
  is being split-tested.
</Tip>

### 4.3 Card panel billing fields

`checkout_settings.billing_fields` controls which inputs the card panel's auto-injected billing block renders. It is surfaced to templates as `checkout.panel_billing_fields`.

```html theme={null}
<script scope="backend">
setVariable("checkout_settings", {
  billing_fields: ['country']   // country only, no ZIP
});
</script>
```

| Value | Effect |
| - | - |
| omitted / `null` | Both Country and ZIP are shown (default) |
| `['country']` | Country select only |
| `['zip']` | ZIP / postal code only |
| `['country', 'zip']` | Both — same as the default |
| `['address']` | Legacy alias for `['zip']`, kept so existing pages keep working |

If the resulting set is empty, the billing block is not rendered at all.

### 4.4 Wallet labels

`checkout_settings.wallet` is surfaced as `checkout.wallet_settings` and its values are handed
straight to Apple on the **Apple Pay recurring payment sheet**. They are not an ElasticFunnels
concept: Apple defines these fields, and Apple requires them on a recurring transaction.

```html theme={null}
<script scope="backend">
setVariable("checkout_settings", {
  wallet: {
    recurring_description: 'Monthly wellness subscription',
    recurring_label: 'Wellness Club',
    management_url: 'https://members.yourdomain.com/subscriptions'
  }
});
</script>
```

| Key | Goes to | Falls back to |
| - | - | - |
| `recurring_description` | the sheet's description of what recurs | the product title, else `Subscription` |
| `recurring_label` | the line item label on the sheet | the product title, else `Subscription` |
| `management_url` | the "manage subscription" link Apple shows the customer | the page's own origin |

<Warning>
  `management_url` should point at a page where the customer can genuinely view and cancel the
  subscription, such as your members area. It is shown to the buyer inside Apple's sheet and in
  their Apple Pay subscription settings afterwards. Leaving it unset silently falls back to the
  checkout page's origin, which is rarely a page that can actually cancel anything.
</Warning>

These apply only when **all** of the following hold: the gateway is NMI with Collect.js, the
product is a subscription, and the page has an Apple Pay container. On a one-time purchase they
are ignored.

***

## 5) Checkout abuse protection (card-testing / velocity)

Optional **progressive** friction on **main sale** card checkout submissions (`POST /process-checkout`). It is **off by default** unless you set `checkout_settings.abuse_protection.enabled` to `true`.

<Info>
  This is separate from **site-wide** page rate limiting / HTML captcha on normal page views. Abuse protection here applies only to the checkout payment submit path when enabled on the checkout page.
</Info>

### 5.1 Configuration

```html theme={null}
<script scope="backend">
setVariable("checkout_settings", {
  abuse_protection: {
    enabled: true,
    mode: 'progressive',
    thresholds: {
      captcha_requests: 8,
      hard_block_requests: 20,
      window_ms: 60000,
      block_duration_ms: 3600000
    }
  }
});
</script>
```

| Key | Type | Default when omitted |
| - | - | - |
| `checkout_settings.abuse_protection.enabled` | boolean | `false` (feature off) |
| `checkout_settings.abuse_protection.mode` | string | `"progressive"` (only mode documented) |
| `thresholds.captcha_requests` | integer | `8` |
| `thresholds.hard_block_requests` | integer | `20` |
| `thresholds.window_ms` | integer | `60000` (1 minute) |
| `thresholds.block_duration_ms` | integer | platform default block window (typically one hour) |

You can omit `thresholds` entirely to use defaults. Partial overrides are merged with defaults for any key you specify.

### 5.2 What is protected

* **In scope:** Main sale submissions to **`POST /process-checkout`** when the request is **not** marked as an upsell (`type` ≠ `upsell`).
* **Out of scope:** One-click upsell charges, PayPal/Klarna flows that do not use the same submit path, and arbitrary API calls. Tighten other surfaces separately if needed.

### 5.3 Session lifecycle

1. When a visitor loads a checkout page, sanitized abuse settings are stored in session (with `brand_id`, checkout `page_id` from the render context, and a timestamp).
2. Each qualifying `POST /process-checkout` is counted per visitor IP inside a **checkout-specific** bucket (not mixed with generic page-view rate limits).
3. If settings are **stale** (e.g. older than 24 hours) or **brand / page** no longer match the request, the stored config is cleared and protection does not apply until the visitor loads checkout again.
4. After a successful **checkout captcha** verification, the visitor receives a **short-lived** “verified” flag for checkout (default **15 minutes**) and the checkout attempt counter for that IP is reset, so legitimate users can complete payment after solving the challenge.

### 5.4 Progressive behavior

Within `window_ms`, counting **checkout submit attempts** for the IP:

| Condition | HTTP | Visitor experience |
| - | - | - |
| Below `captcha_requests` | 200 path | Normal checkout continues. |
| At or above `captcha_requests`, below `hard_block_requests` | `429` | JSON response asks for captcha; checkout UI opens a **modal**, visitor solves math challenge, then checkout **resubmits** automatically. |
| At or above `hard_block_requests` | `403` | Submit blocked for a period (`block_duration_ms`); message indicates too many attempts. |

Local and private IPs are not rate-limited by this checkout guard.

### 5.5 JSON response fields (checkout submit)

When abuse protection returns an error-shaped response, the JSON may include:

| Field | Meaning |
| - | - |
| `success` | `false` |
| `error` | Human-readable message |
| `error_code` | Machine code (see below) |
| `error_type` | `"abuse_protection"` when from this feature |
| `retry_allowed` | `true` when captcha path may retry; `false` on hard block |
| `captcha_required` | `true` when the UI should show the captcha step |
| `captcha_payload` | `{ question, token }` for the modal challenge |

**`error_code` values (submit / middleware)**

| Code | Typical HTTP | Meaning |
| - | - | - |
| `CHECKOUT_CAPTCHA_REQUIRED` | 429 | Solve captcha, then retry submit. |
| `CHECKOUT_HARD_BLOCKED` | 403 | Too many attempts; wait before retrying. |

Captcha verification (handled inside checkout UI, not a merchant integration surface) may return `CHECKOUT_CAPTCHA_INVALID`, `CHECKOUT_CAPTCHA_DISABLED`, `CHECKOUT_CAPTCHA_SAVE_FAILED`, or `CHECKOUT_CAPTCHA_ERROR` if something goes wrong; the UI refreshes the challenge or shows an error.

### 5.6 Tuning and false positives

* Corporate NAT or shared IPs can concentrate traffic on one address; if legitimate buyers are challenged too often, **raise** `captcha_requests` or **widen** `window_ms`.
* For testing, use **low** thresholds only on a **sandbox** checkout or test brand.
* If protection “never fires,” confirm the checkout page was **loaded in the same browser session** before submit (session must contain the config).

***

## 6) Payment panel and submit wiring

Recommended card flow:

```html theme={null}
<checkout-cc-panel data-accepted-cards="visa,mastercard,amex,discover"></checkout-cc-panel>
<div data-checkout-message class="checkout-message"></div>
<button type="button" data-checkout-submit>Pay now</button>
```

<Note>
  Submission is **formless**: the checkout runtime never submits a `<form>`. It listens for a click on `[data-checkout-submit]` (or `.checkout-button`), calls `preventDefault()`, and collects every named / `data-template-value` field from the page wrapper. `type="submit"`, `method="POST"` and `form="..."` are cosmetic.
</Note>

### `<checkout-cc-panel>` attributes

Written on the custom tag, these are read server-side and re-emitted onto the generated `<div class="checkout-cc-panel">`:

| Attribute | Values | Default | Description |
| - | - | - | - |
| `data-accepted-cards` | Comma-separated card names | `visa,mastercard,amex,discover` | Card brands shown in the payment tab and validated during input. Supported: `visa`, `mastercard`, `amex`, `discover`, `diners`, `jcb` |
| `data-applepay` | `"false"` to disable | enabled | When `"false"`, Apple Pay is not rendered inside this panel. See the caveat below. |
| `data-applepay-force` | `"true"` | — | Pre-renders a native `<apple-pay-button>` placeholder and sets `checkout.wallet_visible` immediately |
| `data-paypal` | Merchant ID | — | Enables the PayPal tab (resolved server-side). Ignored unless the ID is a PayPal merchant in this brand. See [PayPal](/merchants/paypal). |
| `data-klarna` | Merchant ID | — | Enables the Klarna tab (resolved server-side). Ignored unless the ID is a Klarna merchant in this brand. |

The panel builds its UI client-side from these attributes and `efScope.checkout`. When PayPal, Klarna, or the Apple Pay tab is active, the panel renders as a tabbed accordion; otherwise it renders card fields only.

<Warning>
  `data-applepay-layout` is **not** in this list. The client-side panel does read `data-applepay-layout` (`"separated"`, `"tab"`, `"inline"`, or unset for auto), but the server-side tag expander does not forward it — the generated `<div>` carries only the attributes above. Setting it on `<checkout-cc-panel>` has no effect. Use `<checkout-wallet />` for an above-the-panel wallet.
</Warning>

<Warning>
  `data-applepay="false"` does not always suppress Google Pay. On **NMI**, a `#googlePay` container is still injected when the visitor is on Android. On **Stripe**, both wallets share one mount point, so it disables both.
</Warning>

### Layout selection

With no wallet tag elsewhere on the page, the panel picks its layout automatically:

| Condition | Layout |
| - | - |
| HTTPS, gateway is NMI or Stripe, `data-applepay` not `"false"`, and no `#applePay` already in the DOM | Apple Pay as a **radio tab** alongside Card (and PayPal / Klarna). The tab relabels to Google Pay if that is what gets detected. |
| Any of the above not met | Legacy **inline** layout — wallet containers above the card fields with an `or pay with card` divider |

Because the tab layout requires that no `#applePay` element already exists, adding `<checkout-wallet />` anywhere on the page automatically stops the panel from rendering its own wallet tab.

### Smart field detection

The card panel automatically detects which checkout fields are present on the page and fills in any gaps:

* **Cardholder name:** If `first_name` **or** `last_name` is missing from the page, a "Cardholder Name" field appears inside the card panel. Note this checks only that pair — `shipping_first_name` / `shipping_last_name` do not satisfy it.
* **Billing block:** If neither `billing_zip` nor `shipping_zip` is on the page, the card panel renders a billing block containing a **Country** select and a **ZIP / postal code** input. It never adds a name or street-address field. Which of the two appear is controlled by `checkout_settings.billing_fields` (section 4.3).
* **Auto-copy:** When billing fields are inside the card panel and no shipping fields exist on the page, billing values are automatically copied to shipping during submission (and vice versa).

This means a minimal checkout page with only email and the payment panel still collects enough billing information for AVS.

### Wallet contact field auto-detection

<Note>
  NMI / Collect.js only. On **Stripe**, the payment request is always created with `requestPayerName`, `requestPayerEmail` and `requestShipping` enabled and no phone request, regardless of which fields are on the page.
</Note>

| Page has | Wallet requests |
| - | - |
| `shipping_address` or `shipping_country` | Shipping postal address |
| `billing_address` or `billing_country` | Billing postal address |
| `first_name`, `shipping_first_name`, or `billing_first_name` | Name |
| `email` | Email |
| `phone` | Phone |
| None of the above (card-only) | No contact fields — just the payment token |

Only first-name variants are checked; `last_name` alone does not trigger the name request. No configuration is needed — for digital products that only need email and payment, the wallet skips address collection entirely.

### `<checkout-wallet />`

Standalone wallet placement. Renders `<div class="ef-wallet-standalone">` containing both the `#applePay` and `#googlePay` containers, so the buttons can sit anywhere on the page:

```html theme={null}
<checkout-wallet force="true" wallets="apple_pay,google_pay" />
<checkout-cc-panel data-accepted-cards="visa,mastercard,amex,discover" data-applepay="false"></checkout-cc-panel>
```

| Attribute | Values | Description |
| - | - | - |
| `force` | `"true"` | Pre-renders a native `<apple-pay-button>` placeholder so iOS shows it immediately, and sets `checkout.wallet_visible` to `true` without waiting for detection |
| `wallets` | `apple_pay`, `google_pay` (comma-separated) | Restricts which wallets are allowed. Emitted as `data-wallets` and used for Stripe's `disableWallets` |

Both are plain attributes, **not** `data-` prefixed. The tag may be self-closing.

`<checkout-apple-pay />` is the legacy single-wallet form of this tag. It accepts `force="true"` and renders only the Apple Pay container. Prefer `<checkout-wallet />` on new pages.

<Note>
  `<checkout-wallet>` and `<checkout-apple-pay>` accept a self-closing form. The other checkout tags — `<checkout-cc-panel>`, `<checkout-personal-details>`, `<checkout-details>`, `<checkout-bump>` — **require an explicit closing tag**. Written self-closing they are neither expanded nor stripped, and pass through to the browser as unknown markup.
</Note>

### Tag content handling

| Tag | Children you write inside it |
| - | - |
| `<checkout-personal-details>` | Preserved, rendered through the template engine, and appended **after** the fields the tag generates |
| `<checkout-details>` | Same — appended after the generated shipping / billing fields |
| `<checkout-cc-panel>` | **Discarded.** The tag is replaced by an empty `<div>` that the client-side panel fills in |

`<checkout-personal-details>` and `<checkout-details>` generate their own inputs (from `data-fields` and `data-shipping-fields` respectively) — you do not write the inputs yourself.

**`<checkout-personal-details>` attributes**

| Attribute | Values | Default |
| - | - | - |
| `data-fields` | Comma-separated: `email`, `phone`, `first_name`, `last_name` | `email,phone` |

**`<checkout-details>` attributes**

| Attribute | Description |
| - | - |
| `data-shipping-fields` | Which shipping fields to render |
| `data-countries` | Country allowlist for the dropdown |
| `data-theme-class` | Extra class applied to the generated container |
| `data-input-style`, `data-label-style` | Inline style strings applied to generated inputs / labels |
| `data-input-border-color`, `data-input-bg-color`, `data-input-text-color`, `data-input-focus-border-color`, `data-input-focus-shadow-color`, `data-input-border-radius`, `data-input-padding` | Generated input theming |
| `data-label-color`, `data-label-bg-color`, `data-label-active-color`, `data-label-font-size`, `data-label-font-weight` | Generated floating-label theming |

### Wallet conditional display

| Key | Meaning |
| - | - |
| `checkout.wallet_available` | `{ applePay, googlePay }`. Starts `false / false` server-side; updated once the payment library detects support, typically 1-2 seconds after load |
| `checkout.wallet_visible` | `true` once a wallet button has actually rendered. Only promoted `false` → `true`, never reset. Set immediately by `force="true"` |

Prefer `wallet_visible` for layout decisions — it will not flicker on first paint the way `wallet_available` does:

```html theme={null}
<checkout-wallet force="true" />

<template-if data-condition="checkout.wallet_visible">
  <div class="or-divider">or pay another way</div>
</template-if>

<checkout-cc-panel data-accepted-cards="visa,mastercard,amex,discover" data-applepay="false"></checkout-cc-panel>
```

### `window.ef.checkout` API

A small JavaScript API for programmatic wallet control:

| Member | Description |
| - | - |
| `ef.checkout.walletAvailable` | Getter returning the same `{ applePay, googlePay }` as `checkout.wallet_available` |
| `ef.checkout.payWithWallet(method)` | Triggers `'applePay'` or `'googlePay'` by clicking the matching `[data-wallet]` button. Requires NMI Collect.js; logs a warning if the wallet or button is unavailable |
| `ef.checkout.onWalletComplete(callback)` | Registers a callback fired after a wallet payment attempt |

See [Apple Pay and Google Pay](/merchants/apple-pay-google-pay) for full setup, configuration, and layout examples.

### Styling checkout fields

Checkout input fields (floating labels, focus rings, active label color) respond to a single CSS variable:

| Variable | Default | Controls |
| - | - | - |
| `--ef-primary` | `#3b82f6` | Focus border color, focus glow, active floating label color |

Set it in the page's `<style>` block to match your brand:

```html theme={null}
<style>
  :root {
    --ef-primary: #FF4500; /* your brand color */
  }
</style>
```

You can also scope it to a specific container instead of `:root`:

```html theme={null}
<style>
  .checkout-form-section {
    --ef-primary: #2b3a5c;
  }
</style>
```

All standard input fields (`ef-floating-input`, `ef-form-input`) and quiz fields (`ef-quiz-floating-input`) inherit the value automatically. No other changes are needed.

### Styling the wallet divider

The divider between the wallet buttons and the card panel uses the `ef-wallet-divider` classes. The platform emits the text in lowercase — `or pay another way` in the separated layout, `or pay with card` in the inline layout — and applies **no styling of its own**, so define these classes in your page's `<style>` block (the `text-transform` below is what makes it render uppercase):

```html theme={null}
<style>
  .ef-wallet-divider {
    display: flex;
    align-items: center;
    margin: 1rem 0;
    gap: 0.75rem;
  }
  .ef-wallet-divider-line {
    flex: 1;
    height: 1px;
    background-color: #e5e7eb;
  }
  .ef-wallet-divider-text {
    color: #9ca3af;
    font-size: 13px;
    text-transform: uppercase;
    letter-spacing: 0.05em;
    white-space: nowrap;
  }
</style>
```

***

## 7) After successful payment (redirects)

* If the server returns `redirectUrl`, the visitor is sent there.
* Otherwise, the default purchase confirmation route is used (query parameters typically include order and email).

Details: [Checkout redirect behavior](/funnels/checkout-redirect-behavior).

***

## 8) Troubleshooting

| Issue | What to check |
| - | - |
| Country/state restriction ignored | `checkout_settings` on backend scope; valid codes; session + server enforcement after page load |
| Abuse protection never triggers | `enabled: true`; visitor opened checkout page first; thresholds not too high; not upsell-only flow |
| Too many captchas | Increase `captcha_requests` or `window_ms`; check shared IP / VPN concentration |
| Hard blocks too aggressive | Increase `hard_block_requests` or `window_ms`; review `block_duration_ms` |

***

## Related docs

* [How to design a checkout page](/guides/how-to-design-a-checkout-page) — build walkthrough and HTML patterns
* [Frontend Template Engine: Checkout](/frontend-template-engine/checkout) — `checkout.*` in templates
* [Frontend Template Engine: Cart](/frontend-template-engine/cart) — cart lines, bumps, qty controls
* [Checkout redirect behavior](/funnels/checkout-redirect-behavior) — post-checkout routing
* [reCAPTCHA setup](/domains/recaptcha-setup) — site-wide captcha (separate from checkout abuse modal)


# Courses
Source: https://docs.elasticfunnels.io/courses/overview

Create structured courses with modules, lessons, and progress tracking — gated by customer enrollment from purchase

Courses let you deliver structured learning content (video, audio, or text lessons) to customers who have purchased access. Each course is organized into **modules** with **lessons** (contents). Enrollment is tied to a product purchase — when a customer buys the linked product, they are automatically enrolled.

## How courses work

```mermaid theme={null}
flowchart LR
    A[Customer buys product] --> B[Enrollment created automatically]
    B --> C[is_assigned = true on that course]
    C --> D[Customer accesses course content]
    D --> E[Progress tracked per lesson]
```

1. You create a course in the ElasticFunnels dashboard with modules and lessons.
2. You link a **product** to that course — purchasing the product grants enrollment.
3. On your course pages, `getCourseForCustomer(slug)` returns `is_assigned: true` for enrolled customers and `false` for everyone else.
4. You gate content in the template: show the full course to enrolled customers, show an "Get access" CTA to others.

## Setting up a course

### 1. Create the course

In the dashboard, go to **Courses** and create a new course. Add:

* **Title**, **slug**, **description**, **cover image**, **instructor name**
* **Category** (optional — used for filtering on the course list page)
* **Modules** — each with a title and one or more **lessons**
* **Lessons** — each has a title, type (`video`, `audio`, or `text`), and a content URL or embed

### 2. Link a product to the course

In the course settings, select the **product** that grants access. When a customer purchases this product, an enrollment record is created automatically.

You can link multiple products to the same course (e.g. a bundle and a standalone SKU both grant access to the same course).

### 3. Create your course pages

You need at minimum two pages:

| Page | Purpose |
| - | - |
| **Course list** | Show all available courses with enrollment status (assigned vs. not) |
| **Course detail** | Show a single course — full content if enrolled, "Get access" CTA if not |

See [Courses — Template Reference](/courses/template) for complete backend script and template examples.

## Enrollment and `is_assigned`

Enrollment is created automatically by `BrandCourseEnrollment` when a purchase conversion is recorded for a product that is linked to a course.

The `is_assigned` flag is resolved per-customer when you call `getCourseForCustomer({ slug })` or `getCourses({ assignedOnly: false })`. It is `true` if the currently logged-in customer has an enrollment record for the course.

`started` is `true` when the enrollment has any progress (at least one lesson completed or in progress).

<Note>
  Customers are automatically logged in after checkout, so a customer who just purchased will have `is_assigned: true` the moment they land on the course page — no extra login step needed.
</Note>

## Progress tracking

Progress is tracked server-side per customer, per lesson. All course functions that resolve enrollment (`getCourseForCustomer`, `getCourses`, `getCoursesForCustomer`) include the customer's progress:

* `completed_content_ids` — array of completed lesson IDs
* `progress_percent` — 0–100
* `is_completed` — `true` when the course reaches 100%
* `current_unfinished_lesson` — object with module/lesson ids, titles, and resume URL when in progress
* `resume_url` — direct resume link when available

The front-end marks lessons complete by calling the progress API (`POST /api/course/courses/:courseId/lessons/:contentId/complete`).

For dashboards and aggregate views, two additional functions are available:

* `getCompletedLessonsCount(opts?)` — returns the total number of completed lessons (optionally filtered by course slug)
* `getCourseProgress(opts?)` — returns a structured summary with per-course and overall lesson counts

See [Template Reference](/courses/template) for full API signatures and examples.

## Course object structure

All course functions return objects with this shape:

```javascript theme={null}
{
  id: 42,
  title: "12-Week Fat Loss Blueprint",
  slug: "fat-loss-blueprint",
  description: "A step-by-step 12-week program combining nutrition, cardio, and strength training.",
  instructor_name: "Coach Sarah Mills",
  cover: "https://cdn.example.com/courses/fat-loss-cover.jpg",   // hero/cover image
  logo: "https://cdn.example.com/courses/fat-loss-logo.png",     // small logo
  image_url: "https://cdn.example.com/courses/fat-loss-card.jpg", // card thumbnail

  category_slug: "weight-loss",
  category_name: "Weight Loss",

  module_count: 4,
  lesson_count: 24,
  estimated_minutes: 120,

  // Enrollment fields (present when the customer has an enrollment):
  is_assigned: true,               // customer is enrolled
  started: false,                  // enrollment has progress
  completed_content_ids: [101, 105, 108],  // IDs of completed lessons
  progress_percent: 31,            // 0–100

  // Only on detail call (getCourseForCustomer, getCourseBySlug):
  modules: [
    {
      id: 10,
      title: "Week 1 — Foundation",
      order: 1,
      contents: [
        {
          id: 101,
          title: "Introduction",
          type: "video",            // 'video' | 'audio' | 'text'
          content_url: "https://...",
          content_embed: "<iframe ...>",  // if embed URL
          description: "...",
          materials: [...],           // downloadable files
          key_takeaways: [...]
        }
      ]
    }
  ],
  total_lesson_count: 24,
}
```

## Related

<CardGroup>
  <Card title="Template Reference" icon="code" href="/courses/template">
    Backend functions, course list, course detail, and access gating examples
  </Card>

  <Card title="Members Area" icon="users" href="/members-area/overview">
    Auth wrapper pattern — protecting pages and reusing login logic
  </Card>

  <Card title="Backend Scripts" icon="terminal" href="/backend-scripts/overview">
    How backend scripts work on .ef pages
  </Card>

  <Card title="Backend Data Functions" icon="database" href="/backend-scripts/data-functions">
    Full reference for all data functions including getCourses
  </Card>
</CardGroup>


# Courses — Template Reference
Source: https://docs.elasticfunnels.io/courses/template

Backend functions and template patterns for course list pages, course detail pages, and access gating

This page covers all backend functions for courses and shows how to use them in `.ef` page templates. See [Courses — Overview](/courses/overview) for setup and enrollment.

***

## Backend functions

All functions are available in `<script scope="backend">` blocks and in `.ef` files.

### `getCourses(opts?)`

Returns all courses for the brand, each with `is_assigned` and `started` for the current customer.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `opts` | object | `{}` | Preferred: `{ assignedOnly, sort, preferredOrder }` |

```javascript theme={null}
// Preferred object style
var allCourses = getCourses({ assignedOnly: false, sort: 'enrollment_oldest_unfinished_first' });
var myCourses = getCourses({ assignedOnly: true });

// Legacy positional style (still supported for backward compatibility)
var allCoursesLegacy = getCourses(false);
var myCoursesLegacy = getCourses(true);
```

`sort` supports:

* `enrollment_oldest_unfinished_first` (default)
* `title_asc`
* `title_desc`
* `preferred` (when used, pass `preferredOrder: ['slug-or-title', ...]`)

### `getCategoriesWithCourses(opts?)`

Same as `getCourses` but grouped by category. Returns an array of `{ category_slug, category_name, courses[] }`.

```javascript theme={null}
var categories = getCategoriesWithCourses({ assignedOnly: false, sort: 'enrollment_oldest_unfinished_first' });
// categories[0].category_name  → "Daily Practices"
// categories[0].courses        → [ { title, slug, is_assigned, ... } ]

// Legacy positional style still supported:
var categoriesLegacy = getCategoriesWithCourses(false);
```

### `getCoursesByCategorySlug(opts)`

Returns courses in a single category. Useful for "Daily practices" or "Advanced" sections on a dashboard.

```javascript theme={null}
var daily = getCoursesByCategorySlug({
  category: 'daily-practices',
  assignedOnly: false,
  sort: 'enrollment_oldest_unfinished_first'
});

// Legacy positional style still supported:
var dailyLegacy = getCoursesByCategorySlug('daily-practices', false);
```

### `getCoursesForCustomer(opts?)`

Returns only courses the current customer is enrolled in (same as `getCourses({ assignedOnly: true })`). Returns `[]` if no session or no enrollments.

```javascript theme={null}
var enrolled = getCoursesForCustomer({ sort: 'enrollment_oldest_unfinished_first' });

// Legacy style still supported:
var enrolledLegacy = getCoursesForCustomer();
```

### `getCourseForCustomer(opts)`

Returns a single course **with** enrollment check — `is_assigned` and `started` are set for the current customer. Also returns the full `modules[]` and `contents[]` tree, plus `progress_percent` and `completed_content_ids`. Use this on the course detail page.

```javascript theme={null}
var course = getCourseForCustomer({ slug: 'tinnitus-recovery' });
// course.is_assigned  → true / false
// course.modules      → full module/lesson tree
// course.progress_percent → 0–100

// Legacy positional style still supported:
var courseLegacy = getCourseForCustomer('tinnitus-recovery');
```

Returns `null` if no course with that slug exists.

### `getCourseBySlug(slug)`

Returns a single course **without** enrollment check. `is_assigned` and `started` will not be set. Use when you only need course metadata and don't need to gate content.

```javascript theme={null}
var course = getCourseBySlug('tinnitus-recovery');
```

### `getCourseLesson(opts)`

Returns the resolved current lesson payload for lesson-player pages, including `currentLesson`, `prevLessonUrl`, `nextLessonUrl`, and progress stats.

```javascript theme={null}
var lessonSeed = getCourseLesson({
  course: 'tinnitus-recovery',
  module: 12,
  lesson: 77
});

// Legacy positional style still supported:
var lessonSeedLegacy = getCourseLesson('tinnitus-recovery', 12, 77);
```

### `getCompletedLessonsCount(opts?)`

Returns the total number of completed lessons across all enrolled courses, or for a specific course when a slug is provided.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `opts` | object | `undefined` | Optional. Pass `{ course: 'slug' }` to count only a specific course. Omit for all courses. |

```javascript theme={null}
var totalDone = getCompletedLessonsCount();           // all courses
var courseDone = getCompletedLessonsCount({ course: 'tinnitus-recovery' }); // single course

// Legacy shorthand still supported:
var courseDoneLegacy = getCompletedLessonsCount('tinnitus-recovery');
```

Returns `0` if the customer has no enrollments or no completed lessons.

### `getCourseProgress(opts?)`

Returns a structured progress summary with completed/total lesson counts per course and an overall total. Useful for dashboards.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `opts` | object | `undefined` | Optional. Pass `{ course: 'slug' }` to limit to a single course. Omit for all courses. |

```javascript theme={null}
var progress = getCourseProgress();
// progress.completedLessons  → 12   (total across all courses)
// progress.totalLessons      → 48   (total across all courses)
// progress.courses           → [
//   { slug: 'tinnitus-recovery', title: '...', completedLessons: 5, totalLessons: 16, progressPercent: 31 },
//   { slug: 'cbt-program', title: '...', completedLessons: 7, totalLessons: 32, progressPercent: 22 }
// ]

var single = getCourseProgress({ course: 'tinnitus-recovery' });
// single.completedLessons → 5
// single.courses          → [ { slug: 'tinnitus-recovery', ... } ]

// Legacy shorthand still supported:
var singleLegacy = getCourseProgress('tinnitus-recovery');
```

### `request.route_params`

For dynamic slug pages (e.g. `guided-course/{course}.ef`), the slug is available via `request.route_params.course`.

***

## Course list page

Show all courses, sorted so enrolled courses appear first. Use `is_assigned` and `started` to drive the CTA label.

```html theme={null}
<script scope="backend">
  if (!is_customer) {
    redirect('/members-login');
  }

  var allCourses = getCourses({ assignedOnly: false, sort: 'enrollment_oldest_unfinished_first' });

  // Sort: enrolled first, then among enrolled put started (Continue) before not started
  allCourses = allCourses.slice().sort(function(a, b) {
    if (a.is_assigned !== b.is_assigned) return b.is_assigned - a.is_assigned;
    return b.started - a.started;
  });

  setVariable('courses', allCourses);
  setVariable('courseCount', allCourses.length);
</script>

@if(var.courseCount gt 0)
<div class="course-grid">
  @foreach(c in var.courses)
  <div class="course-card">
    @if(c.image_url)
    <img src="{{ c.image_url }}" alt="{{ c.title }}" />
    @endif

    <h3>{{ c.title }}</h3>
    <p>{{ c.description }}</p>
    <p>{{ c.module_count }} modules · {{ c.lesson_count }} lessons</p>

    @if(c.is_assigned eq false)
    <a href="/buy/{{ c.slug }}-access" class="btn-secondary">Get access</a>
    @elseif(c.started)
    <a href="/course/{{ c.slug }}" class="btn-primary">Continue</a>
    @else
    <a href="/course/{{ c.slug }}" class="btn-primary">Start Course</a>
    @endif
  </div>
  @endforeach
</div>
@else
<p>No courses available yet.</p>
@endif
```

### With category tabs

```html theme={null}
<script scope="backend">
  if (!is_customer) { redirect('/members-login'); }

  var categories = getCategoriesWithCourses({ assignedOnly: false, sort: 'enrollment_oldest_unfinished_first' });

  // Sort courses within each category: assigned first
  categories = categories.map(function(cat) {
    var sorted = (cat.courses || []).slice().sort(function(a, b) {
      if (a.is_assigned !== b.is_assigned) return b.is_assigned - a.is_assigned;
      return b.started - a.started;
    });
    return { category_slug: cat.category_slug, category_name: cat.category_name, courses: sorted };
  });

  setVariable('categories', categories);
</script>

@foreach(cat in var.categories)
<section data-category="{{ cat.category_slug }}">
  <h2>{{ cat.category_name }}</h2>
  <div class="course-grid">
    @foreach(c in cat.courses)
    <div class="course-card">
      <h3><a href="/course/{{ c.slug }}">{{ c.title }}</a></h3>
      <span>
        @if(c.is_assigned eq false)
          Get access
        @elseif(c.started)
          Continue
        @else
          Start Course
        @endif
      </span>
    </div>
    @endforeach
  </div>
</section>
@endforeach
```

***

## Course detail page

Resolve the slug from the URL, check enrollment with `getCourseForCustomer`, and gate content.

```html theme={null}
<script scope="backend">
  if (!is_customer) {
    redirect('/members-login');
  }

  // For a dynamic page named guided-course/{course}.ef:
  var slug = request.route_params.course;

  // For a fixed page reading slug from query string:
  // var slug = request.query.course;

  var course = getCourseForCustomer({ slug: slug });

  if (!course) {
    redirect('/courses');
  }

  setVariable('course',       course);
  setVariable('isAssigned',   course.is_assigned || false);
  setVariable('courseStarted', course.started || false);

  if (course.is_assigned) {
    // Track that the customer has visited this course (optional)
    setSessionItem('course_visited_' + slug, '1');
  }
</script>

@if(var.course)

  <!-- Hero -->
  <div class="course-hero">
    @if(var.course.cover)
    <img src="{{ var.course.cover }}" alt="{{ var.course.title }}" />
    @endif
    <h1>{{ var.course.title }}</h1>
    @if(var.course.instructor_name)
    <p>by {{ var.course.instructor_name }}</p>
    @endif
  </div>

  <!-- Stats -->
  <div class="course-stats">
    <span>{{ var.course.module_count }} modules</span>
    <span>{{ var.course.total_lesson_count }} lessons</span>
  </div>

  @if(var.isAssigned)

  <!-- Progress -->
  <div class="progress-bar" style="width: {{ var.course.progress_percent }}%"></div>
  <p>{{ var.course.progress_percent }}% complete</p>

  <!-- Modules and lessons -->
  @foreach(mod in var.course.modules)
  <div class="module" id="module-{{ mod.id }}">
    <h2>{{ mod.order }}. {{ mod.title }}</h2>
    <div class="lessons">
      @foreach(lesson in mod.contents)
      <div class="lesson-row"
           data-content-id="{{ lesson.id }}"
           data-content-url="{{ lesson.content_url }}">
        <span class="lesson-title">{{ lesson.title }}</span>
        @if(lesson.type == 'video')
        <span class="badge">Video</span>
        @elseif(lesson.type == 'audio')
        <span class="badge">Audio</span>
        @endif
      </div>
      @endforeach
    </div>
  </div>
  @endforeach

  @else

  <!-- Not enrolled — show CTA -->
  <div class="access-gate">
    <p>You don't have access to this course yet.</p>
    <a href="/courses" class="btn">Browse all courses</a>
  </div>

  @endif

@else
<p>Course not found. <a href="/courses">Back to courses</a></p>
@endif
```

***

## Auth wrapper for course pages

Use the [auth wrapper pattern](/members-area/overview#auth-wrapper-pattern-recommended) (`@extends`) so the login check and common data load happen once across all course pages:

```html theme={null}
{{-- members-courses-layout.ef --}}
<script scope="backend">
  if (!is_customer) {
    redirect('/members-login?next=' + encodeURIComponent(request.path));
  }
</script>
@block("content") @endblock
```

Then each course page:

```html theme={null}
{{-- course-list.ef --}}
@extends("members-courses-layout")
@block("content")

<script scope="backend">
  var courses = getCourses({ assignedOnly: false });
  setVariable('courses', courses);
</script>

@foreach(c in var.courses)
  <p>{{ c.title }} — @if(c.is_assigned)Enrolled @else Get access @endif</p>
@endforeach

@endblock
```

***

## Checking access to a specific product

If you want to gate course access by checking whether the customer bought a specific product (rather than relying on enrollment), you can cross-reference with `getOrders()`:

```html theme={null}
<script scope="backend">
  if (!is_customer) { redirect('/members-login'); }

  var course = getCourseForCustomer({ slug: request.route_params.course });
  if (!course) { redirect('/courses'); }

  // Fallback: check order history for a product by name
  if (!course.is_assigned) {
    var orders = getOrders('newest', 100);
    for (var i = 0; i < orders.length; i++) {
      for (var j = 0; j < orders[i].products.length; j++) {
        if (orders[i].products[j].name === 'Course Access Pass') {
          course.is_assigned = true;
        }
      }
    }
  }

  setVariable('course', course);
  setVariable('isAssigned', course.is_assigned);
</script>
```

<Note>
  Prefer the enrollment-based check (`getCourseForCustomer`) — it is more reliable and does not require iterating order history. Use the order-history fallback only if enrollment is not being set up via product linking.
</Note>

***

## Lesson types and content

Each lesson in `mod.contents` has a `type` field:

| `type` | Content fields |
| - | - |
| `'video'` | `content_url` (direct video URL) or `content_embed` (iframe HTML) |
| `'audio'` | `content_url` (audio file URL) |
| `'text'` | `content` (HTML body) |

Additional fields on each lesson:

| Field | Description |
| - | - |
| `title` | Lesson title |
| `description` | Short description shown below the player |
| `content_under` | Additional text shown under video/audio (e.g. transcript excerpt) |
| `materials` | Array of `{ name, url }` — downloadable files |
| `key_takeaways` | Array of strings — bullet-point summary |

***

## Progress API

All progress routes are prefixed with `/api/course/courses/:courseId/`. Authentication is via the active course session (cookie). `courseId`, `moduleId`, and `contentId` are numeric IDs.

### Mark a lesson complete

```javascript theme={null}
// POST /api/course/courses/:courseId/modules/:moduleId/lessons/:contentId/complete
fetch(`/api/course/courses/${courseId}/modules/${moduleId}/lessons/${contentId}/complete`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({})
});
```

Returns `{ success: true, message, stats: { completed_lessons, total_lessons, completion_percent } }`.

### Save general progress

`courseId`, `moduleId`, and `contentId` go in the URL for the lesson-specific routes. The general `saveProgress` route keeps them in the body — useful when you want to upsert a progress record with a specific `completed` value (e.g. un-completing).

```javascript theme={null}
// POST /api/course/courses/:courseId/progress
fetch(`/api/course/courses/${courseId}/progress`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    module_id: moduleId,      // required
    content_id: contentId,    // required
    completed: true,          // boolean
    progress_percent: 100,    // 0–100
    video_position: 0,        // seconds
    video_duration: 0         // seconds
  })
});
```

### Save video position

```javascript theme={null}
// POST /api/course/courses/:courseId/modules/:moduleId/lessons/:contentId/video-progress
fetch(`/api/course/courses/${courseId}/modules/${moduleId}/lessons/${contentId}/video-progress`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    video_position: 142,    // seconds elapsed
    video_duration: 600,    // total duration in seconds
    progress_percent: 24    // 0–100; auto-completes lesson at ≥ 90%
  })
});
```

### Get all progress for a course

```javascript theme={null}
// GET /api/course/courses/:courseId/progress
const res = await fetch(`/api/course/courses/${courseId}/progress`);
const { progress, stats } = await res.json();
// progress → array of per-lesson progress objects
// stats    → { completed_lessons, total_lessons, completion_percent, last_accessed_at, ... }
```

### Get progress for a single lesson

```javascript theme={null}
// GET /api/course/courses/:courseId/modules/:moduleId/lessons/:contentId/progress
const res = await fetch(
  `/api/course/courses/${courseId}/modules/${moduleId}/lessons/${contentId}/progress`
);
const { progress } = await res.json();
// progress → { completed, progress_percent, video_position, video_duration } or null
```

### Get course stats

```javascript theme={null}
// GET /api/course/courses/:courseId/stats
const res = await fetch(`/api/course/courses/${courseId}/stats`);
const { stats } = await res.json();
```

The page receives the initial completed IDs via `course.completed_content_ids`. Use this array to mark lessons visually on load, then update the UI optimistically when the API call succeeds.


# CRM Overview
Source: https://docs.elasticfunnels.io/crm/overview

Build custom data applications on top of ElasticFunnels with the CRM module.

The CRM module lets you define custom entity types, fields, pipelines, and stages — then store structured data entries linked to any record in the system. Think of it as both a **customer relations management** tool and a **general-purpose data platform** (like Webflow CMS Collections). You can create traditional pipeline-based entities (deals, contacts) or standalone data collections (properties, inventory, cities).

## How entries attach to records

Each CRM entry is linked to a record in your funnel or store through two values:

| Field | Description |
| - | - |
| `reference_type` | The type of record (e.g. `customer`, `order`, `lead`) |
| `reference_id` | The ID of that record |

This pattern lets you attach structured data to customers, orders, or custom reference types you define.

## Concepts

<Note>
  **Entries vs. Fields**: An **entry** is a single record or document stored in the CRM (like a row in a database, representing e.g. a specific check-in for a customer). A **field** is a specific piece of data that lives inside an entry (like a column, e.g. "current\_weight" or "deal\_value").
</Note>

### Entity Modes

Entities operate in one of two modes:

| Mode | Description |
| - | - |
| **CRM** (default) | Traditional pipeline-based entity with stages, suitable for deals, leads, contacts |
| **Data** | Standalone data collection without pipelines — ideal for storing structured records like properties, inventory items, cities, products |

When creating an entity, choose "Data Collection" to skip pipelines entirely. Data-mode entities focus purely on fields and entries.

### Entities

An **entity** defines a type of CRM record (e.g. "Deals", "Contacts", "Properties"). Each entity has:

* A **name** and **slug** (machine-readable identifier)
* An **entity mode** (`crm` or `data`)
* **Fields** that define the data structure
* **Pipelines** with **stages** for workflow tracking (CRM mode only)

### Fields

Fields define what data can be stored on entries. Each field has:

| Property | Description |
| - | - |
| `label` | Human-readable label |
| `key` | Machine-readable key (used in API and templates) |
| `type` | See supported types below |
| `ui_editable` | Whether this field can be edited in the admin UI (default `true`) |
| `reporting_config` | Optional analytics metadata for CRM reports |

#### Supported field types

| Type | Renders as | Notes |
| - | - | - |
| `text` | Text input | Default type |
| `textarea` | Multi-line text | |
| `rich_text`, `wysiwyg` | Rich text | Formatted content stored as HTML |
| `email` | Email input | Rendered as mailto link |
| `phone` | Phone input | Rendered as tel link |
| `url` | URL input | Rendered as clickable link |
| `number` | Numeric input | Stored as double |
| `date` | Date picker | ISO 8601 string |
| `datetime` | Date+time picker | ISO 8601 string |
| `boolean` | Toggle switch | true/false |
| `select` | Dropdown | Requires `options` array |
| `multiselect` | Multi-select tags | Requires `options` array |
| `color` | Color picker | Hex color code |
| `image` | Image URL / uploader | Renders as thumbnail |
| `file` | File URL / uploader | Renders as download link |
| `json` | JSON editor | Renders as collapsible tree |
| `reference` | Entity reference | Links to single entry in another entity |
| `multi_reference` | Multi-reference | Links to multiple entries in another entity |

The **type** in CRM settings controls how the field appears and behaves in the admin UI. It does **not** change what you pass from code: `setCrmField` always sends a JavaScript **value** — a **string**, **number**, **boolean**, or a **JSON object**. For fields configured as **date** in the CRM, pass a **date-time string** from scripts, typically **ISO 8601** (e.g. `new Date().toISOString()` or `'2026-03-15'`).

#### UI-editable fields

Set `ui_editable: false` on fields that should only be updated programmatically (via backend scripts). These fields display with a lock icon in the admin UI and cannot be inline-edited.

Use `reporting_config` to mark fields as reportable and suggest how the Reports tab should aggregate and chart them. Supported values include `reportable`, `aggregation_type` (`numeric`, `categorical`, `date`, `boolean`), `baseline` (`min`/`max`), `bucket_size`, and `preferred_chart` (`kpi`, `histogram`, `pie`, `bar`, `line`).

### Relations

Relations link entries across entities. A field of type `reference` or `multi_reference` creates a relation between the current entity and a target entity. Relations are stored in Elasticsearch alongside the entry data.

#### Configuring reference fields

When creating a reference field, specify:

* **Target entity**: Which entity the reference points to
* **Display field**: Which field from the target entity to show as the label (defaults to title)

#### Working with relations programmatically

Use `SetCrmRelation` and `RemoveCrmRelation` to manage relations. These two are **template-engine functions** — they are not available in backend scripts:

```javascript theme={null}
SetCrmRelation({
  slug: 'properties',
  relationKey: 'city',
  targetEntryId: 'abc123'
});

RemoveCrmRelation({
  slug: 'properties',
  relationKey: 'city',
  targetEntryId: 'abc123'
});
```

### Pipelines & Stages

Pipelines represent workflows (CRM mode only). Each pipeline contains ordered stages with optional colors and semantic statuses (e.g. `won`, `lost`, `active`). Entries move through stages as they progress.

## Customer CRM Data

The most common pattern is linking CRM entries to customers. When a customer visits a page, their session supplies the customer context so CRM defaults attach to the right person (creating the customer record when needed).

### Example: Weight Loss Tracker

1. Create a CRM entity called "Weight Tracker" with slug `weight-tracker` and fields like `current_weight`, `goal_weight`, `last_checkin`
2. Create a pipeline "Progress" with stages "Starting", "In Progress", "Goal Reached"
3. Store data via backend scripts or the template engine:

```javascript theme={null}
setCrmFields({
  slug: 'weight-tracker',
  fields: [
    { fieldKey: 'current_weight', value: 185 },
    { fieldKey: 'goal_weight', value: 165 },
    { fieldKey: 'last_checkin', value: '2026-03-15' }
  ]
});
```

<Tip>
  `slug` identifies the **CRM entity** (board/type). `referenceType` / `referenceId` default to the current **customer** when omitted. For another record: `setCrmField({ slug: 'weight-tracker', referenceType: 'order', referenceId: '12345', fieldKey: 'status', value: 'shipped' })`. See [Data Functions](/backend-scripts/data-functions#crm-data).
</Tip>

4. Read it back on any page:

```javascript theme={null}
var weight = getCrmField({ slug: 'weight-tracker', fieldKey: 'current_weight' });
var goal = getCrmField({ slug: 'weight-tracker', fieldKey: 'goal_weight' });
if (weight && goal && Number(weight) <= Number(goal)) {
  setVariable('show_congrats', true);
}
```

### Viewing Customer CRM Data

Customer CRM entries are visible in the **Customer Details** page under the **CRM** tab. This shows all CRM entries linked to that customer across all entity types.

## Functions

Write functions accept an optional `async` parameter (default `false`). When `true`, the write runs in the background for faster response times. Read functions are always synchronous.

<Warning>
  **The function names differ between the two runtimes, and calling the wrong one takes the page down.**

  * **Template engine** (`{{ }}` / `@if` inside a page or component) — **PascalCase**: `SetCrmFields({...})`
  * **Backend scripts** (`<script scope="backend">` and standalone `scripts/*.js`) — **camelCase**: `setCrmFields({...})`

  An undefined function is not ignored — it aborts the render, and a live page starts returning **404**. Three functions exist in **templates only** (`CreateCrmEntry`, `SetCrmRelation`, `RemoveCrmRelation`) and `reassignCrmReference` exists in **backend scripts only**; there is no `createCrmEntry` in a backend script. To create an entry from a backend script use `addCrmFieldValue({...})`, or `setCrmFields({...})` to upsert.

  Test with a draft and open the preview URL before publishing.
</Warning>

The table below uses the **backend-script (camelCase)** spelling. For the template engine, capitalise the first letter.

| Function | Description |
| - | - |
| `ensureCrmEntity({ slug, ... })` | Idempotently create an entity with fields (returns `{ id, slug, created, fields_added }`) |
| `CreateCrmEntry({ slug, title?, values?, ... })` | **Template engine only.** Create a new entry and return its ID. In a backend script use `addCrmFieldValue` / `setCrmFields` instead |
| `getCrmEntries({ slug, ... })` | Fetch all entries for one entity **slug** + reference |
| `getCrmField({ slug, fieldKey, ... })` | Get one field value (`slug` + `fieldKey` required) |
| `getCrmFields({ slug, fieldKeys, ... })` | Get multiple field values (`slug` + `fieldKeys` required) |
| `setCrmField({ slug, fieldKey, value, ... })` | Set one field value — upserts a single value per key |
| `setCrmFields({ slug, fields, ... })` | Set multiple field values in one read/write cycle |
| `addCrmFieldValue({ slug, fieldKey, value, ... })` | Append a new entry with a field value — enables multiple values per key |
| `getCrmFieldValues({ slug, fieldKey, ... })` | Get all values for a field key across entries (returns array) |
| `clearCrmEntries({ slug, ... })` | Delete all entries for an entity slug + reference |
| `SetCrmRelation({ slug, relationKey, targetEntryId, ... })` | **Template engine only.** Add a relation from entry to another entry |
| `RemoveCrmRelation({ slug, relationKey, targetEntryId, ... })` | **Template engine only.** Remove a specific relation |
| `reassignCrmReference({ slug, fromReferenceType, fromReferenceId, ... })` | **Backend scripts only.** Move entries from one visitor reference to another (e.g. anonymous → customer after login) |
| `moveCrmLead({ slug, pipelineId/pipelineSlug, stageId/stageSlug, ... })` | Move entry to a specific pipeline + stage |
| `moveCrmToStage({ slug, stageId/stageSlug, ... })` | Move entry to a stage (pipeline resolved from stage) |
| `moveCrmToPipeline({ slug, pipelineId/pipelineSlug, ... })` | Move entry to a pipeline (lands on first stage) |
| `moveCrmToEntity({ fromSlug, toSlug, fieldMap, ... })` | Copy mapped fields across entity types |

`slug` is always required (the entity's slug from CRM settings). Reference defaults: `customer` + session customer id.

### Common options

Every CRM function accepts these optional properties:

| Property | Type | Default | Description |
| - | - | - | - |
| `referenceType` | string | `'customer'` | Linked record type |
| `referenceId` | string | session `customer_id` | Linked record id |

Write functions also accept:

| Property | Type | Default | Description |
| - | - | - | - |
| `async` | boolean | `false` | When `true`, writes run in the background — faster but eventual consistency |

### Single-value fields

Use `setCrmField` / `getCrmField` for fields that hold one value per key (e.g. weight, goal, last check-in date):

```javascript theme={null}
setCrmField({ slug: 'weight-tracker', fieldKey: 'current_weight', value: 182 });
var weight = getCrmField({ slug: 'weight-tracker', fieldKey: 'current_weight' });
```

When you need to read multiple fields at once, use `getCrmFields` and pass an array of `fieldKeys`:

```javascript theme={null}
var fields = getCrmFields({ slug: 'weight-tracker', fieldKeys: ['current_weight', 'goal_weight'] });
var weight = fields.current_weight;
var goal = fields.goal_weight;
```

When writing multiple fields in one script, prefer `setCrmFields` so all values are merged in one read/write cycle:

```javascript theme={null}
setCrmFields({
  slug: 'weight-tracker',
  fields: [
    { fieldKey: 'current_weight', value: 182 },
    { fieldKey: 'goal_weight', value: 165 },
    { fieldKey: 'last_checkin', value: today }
  ]
});
```

If you need to keep separate `setCrmField` calls, pass `force: true` to skip the per-key scan and merge directly into the newest entry — much faster for sequential writes:

```javascript theme={null}
setCrmField({ slug: 'weight-tracker', fieldKey: 'current_weight', value: 182, force: true });
setCrmField({ slug: 'weight-tracker', fieldKey: 'goal_weight', value: 165, force: true });
setCrmField({ slug: 'weight-tracker', fieldKey: 'last_checkin', value: today, force: true });
```

### Multi-value fields

Use `addCrmFieldValue` / `getCrmFieldValues` when a key can have multiple values over time (e.g. weigh-in history). Each `addCrmFieldValue` call creates a separate CRM entry:

```javascript theme={null}
addCrmFieldValue({
  slug: 'weight-tracker',
  fieldKey: 'weighin_history',
  value: { date: '2026-03-31', weight: 182, notes: 'post-workout' }
});

var history = getCrmFieldValues({ slug: 'weight-tracker', fieldKey: 'weighin_history', limit: 10 });
// Returns an array of values, newest first
```

### Clearing entries

Use `clearCrmEntries` to delete all entries for an entity + reference:

```javascript theme={null}
var result = clearCrmEntries({ slug: 'weight-tracker' });
// { ok: true, deleted: 3 }
```

### Pipeline and stage movement

Use `moveCrmLead` to move a CRM entry to a specific pipeline and stage by id or slug:

```javascript theme={null}
// By slug (recommended — works across environments)
moveCrmLead({ slug: 'deals', pipelineSlug: 'sales', stageSlug: 'qualified' });

// By id
moveCrmLead({ slug: 'deals', pipelineId: 3, stageId: 12 });
```

Returns `{ ok, moved, totalMatched, pipeline_id, stage_id }`. `moved` is the number of entries updated (1 unless `allEntries: true`).

Use `moveCrmToStage` when you only know the stage — the pipeline is resolved automatically:

```javascript theme={null}
moveCrmToStage({ slug: 'deals', stageSlug: 'won' });
```

Use `moveCrmToPipeline` to move an entry into a pipeline; it lands on the first stage:

```javascript theme={null}
moveCrmToPipeline({ slug: 'deals', pipelineSlug: 'onboarding' });
```

Use `moveCrmToEntity` to copy field values from one entity type to another (e.g. promoting a lead to a deal):

```javascript theme={null}
moveCrmToEntity({
  fromSlug: 'leads',
  toSlug: 'deals',
  fieldMap: { lead_score: 'initial_score', source: 'lead_source' },
  pipelineSlug: 'sales',
  stageSlug: 'new',
  removeFromOld: false  // set true to delete source entries after copy
});
```

Returns `{ ok, moved, removed_from_old }`.

Pass `allEntries: true` to any move function to update all matching entries instead of just the newest one.

### Ensuring entities programmatically

Use `EnsureCrmEntity` at the top of a backend script to idempotently provision an entity. Re-runs never overwrite admin edits — only missing fields are added.

```javascript theme={null}
EnsureCrmEntity({
  slug: 'properties',
  name: 'Properties',
  singularName: 'Property',
  pluralName: 'Properties',
  entityMode: 'data',  // 'crm' (default) or 'data'
  icon: 'building',
  fields: [
    { key: 'address', label: 'Address', type: 'text' },
    { key: 'price', label: 'Price', type: 'number' },
    { key: 'bedrooms', label: 'Bedrooms', type: 'number' },
    { key: 'photo', label: 'Photo', type: 'image', ui_editable: false },
    { key: 'city', label: 'City', type: 'reference', options: { target_entity_id: 5 } },
    { key: 'status', label: 'Status', type: 'select', options: ['available', 'sold', 'pending'] },
    {
      key: 'listing_date',
      label: 'Listing Date',
      type: 'date',
      reportingConfig: { reportable: true, aggregationType: 'date' }
    }
  ]
});
```

### Creating entries

Use `CreateCrmEntry` to create a new entry and get back its ID (useful for setting relations). This is a **template-engine function** — from a backend script use `addCrmFieldValue({ slug, fieldKey, value })` or `setCrmFields({ slug, fields })` instead, as there is no `createCrmEntry` there:

```javascript theme={null}
var result = CreateCrmEntry({
  slug: 'properties',
  title: '123 Main St',
  values: {
    address: '123 Main Street, Springfield',
    price: 450000,
    bedrooms: 3,
    status: 'available'
  }
});
// result = { ok: true, id: 'abc123' }
```

### Managing relations

Use `SetCrmRelation` to link entries:

```javascript theme={null}
// Link a property to a city
SetCrmRelation({
  slug: 'properties',
  relationKey: 'city',
  targetEntryId: 'city-entry-id-here'
});
```

Use `RemoveCrmRelation` to unlink:

```javascript theme={null}
RemoveCrmRelation({
  slug: 'properties',
  relationKey: 'city',
  targetEntryId: 'city-entry-id-here'
});
```

### Async writes

For non-critical writes where you don't need immediate consistency, pass `async: true` so the write runs in the background:

```javascript theme={null}
setCrmField({ slug: 'weight-tracker', fieldKey: 'last_page_view', value: today, async: true });
setCrmFields({ slug: 'weight-tracker', fields: [{ fieldKey: 'current_weight', value: 182 }, { fieldKey: 'last_checkin', value: today }], async: true });
addCrmFieldValue({ slug: 'weight-tracker', fieldKey: 'page_views', value: { url: '/dashboard', ts: today }, async: true });
moveCrmLead({ slug: 'deals', pipelineSlug: 'sales', stageSlug: 'contacted', async: true });
```

See [Data Functions](/backend-scripts/data-functions#crm-data) for full parameter details and examples.


# Building Custom Workflows
Source: https://docs.elasticfunnels.io/crm/post-workflow

Use pages as API endpoints — accept POST data, validate it, and store CRM entries from frontend to backend.

Pages accept both `GET` and `POST` requests. Combined with [backend scripts](/backend-scripts/overview), this lets you build data-collection endpoints, custom forms, and mini-apps using regular ElasticFunnels pages — no external server needed.

## The pattern

1. Create a page (e.g. `/weight/checkin`)
2. Add a `<script scope="backend">` that checks for `POST`, validates `request.body` with the [Schema validator](/backend-scripts/validation), and stores the data
3. Your frontend uses `fetch()` to POST JSON data to that page
4. The backend script responds with JSON — the page HTML is skipped when `response.json()` is called

For reusable validation logic across multiple pages, use [shared backend script modules](/backend-scripts/imports) — create a module with exported functions and import them anywhere.

## Full example: Weight check-in

### 1. Create a shared validation module

Create a backend script module (code: `validators`) with shared schemas:

```html theme={null}
<script scope="backend">
  export var WeightCheckinSchema = Schema.object({
    weight:  Schema.number().required().min(50).max(500),
    unit:    Schema.string().valid('lbs', 'kg').default('lbs'),
    notes:   Schema.string().max(500).default(''),
  });

  export function requireCustomer() {
    if (!is_customer) {
      response.status(401);
      response.json({ ok: false, error: 'not authenticated' });
    }
  }
</script>
```

### 2. Create the page `/weight/checkin`

```html theme={null}
<script scope="backend">
  import { WeightCheckinSchema, requireCustomer } from "validators";

  if (request.method === 'POST') {
    requireCustomer();

    var result = WeightCheckinSchema.validate(request.body);

    if (!result.valid) {
      response.status(400);
      response.json({ ok: false, errors: result.errors });
    }

    var data = result.value;

    var entitySlug = 'pattern-tracker'; // your CRM entity slug from settings
    var fields = [
      { fieldKey: 'current_weight', value: data.weight },
      { fieldKey: 'weight_unit', value: data.unit },
      { fieldKey: 'last_checkin', value: new Date().toISOString() }
    ];

    if (data.notes) {
      fields.push({ fieldKey: 'checkin_notes', value: data.notes });
    }

    setCrmFields({ slug: entitySlug, fields: fields });

    response.json({ ok: true, data: data });
  }

  setVariable('page_title', 'Weight Check-in');
</script>

<div>
  <h1>{{ var.page_title }}</h1>
  <form id="checkin-form">
    <input type="number" id="weight" placeholder="Current weight" step="0.1" required />
    <select id="unit">
      <option value="lbs">lbs</option>
      <option value="kg">kg</option>
    </select>
    <textarea id="notes" placeholder="Notes (optional)"></textarea>
    <button type="submit">Log Weight</button>
  </form>
  <div id="result"></div>
</div>

<script>
document.getElementById('checkin-form').addEventListener('submit', async function(e) {
  e.preventDefault();

  var res = await fetch('/weight/checkin', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      weight: parseFloat(document.getElementById('weight').value),
      unit: document.getElementById('unit').value,
      notes: document.getElementById('notes').value
    })
  });

  var data = await res.json();
  document.getElementById('result').textContent = data.ok
    ? 'Logged: ' + data.data.weight + ' ' + data.data.unit
    : 'Error: ' + (data.errors || [data.error]).join(', ');
});
</script>
```

### 3. Read the data back on another page

On any page (e.g. `/dashboard`), read the CRM data:

```html theme={null}
<script scope="backend">
  import { requireCustomer } from "validators";
  requireCustomer();

  var entitySlug = 'pattern-tracker';
  var fields = getCrmFields({ slug: entitySlug, fieldKeys: ['current_weight', 'goal_weight'] });
  var weight = fields.current_weight;
  var goal   = fields.goal_weight;
  setVariable('current_weight', weight || 'Not logged yet');
  setVariable('goal_weight', goal || 'Not set');
  setVariable('on_track', weight && goal && Number(weight) <= Number(goal));
</script>

<h2>Current weight: {{ var.current_weight }}</h2>
<h2>Goal: {{ var.goal_weight }}</h2>
<p v-if="var.on_track">You've reached your goal!</p>
```

## How it fits together

```
Frontend (browser)             Backend (sandbox)
─────────────────              ─────────────────
fetch('/weight/checkin', {     → request.method = 'POST'
  method: 'POST',               request.body = { weight: 182, ... }
  body: JSON.stringify(data)
})                             → Schema.validate(request.body)
                              → setCrmFields({ slug: 'pattern-tracker', fields: [...] })
← { ok: true, data: {...} }   ← response.json({ ok: true, data })
```

## CRM functions reference

| Function | Description |
| - | - |
| `getCrmEntries({ slug, ... })` | Fetch entries — **`slug` required** ([Data Functions](/backend-scripts/data-functions#crm-data)) |
| `getCrmField({ slug, fieldKey, ... })` | Get one field |
| `getCrmFields({ slug, fieldKeys, ... })` | Get multiple fields at once |
| `setCrmField({ slug, fieldKey, value, ... })` | Set one field |
| `setCrmFields({ slug, fields, ... })` | Set multiple fields in one call |
| `moveCrmToStage({ slug, stageId \| stageSlug, ... })` | Move an entry to a specific stage |
| `moveCrmToPipeline({ slug, pipelineId \| pipelineSlug, stageId \| stageSlug?, ... })` | Move an entry into a pipeline |
| `moveCrmToEntity({ fromSlug, toSlug, fieldMap, ... })` | Move mapped fields to another CRM entity |
| `moveCrmLead({ slug, pipelineId \| pipelineSlug, stageId \| stageSlug, ... })` | Direct workflow move (compatibility helper) |
| `reassignCrmReference({ slug, fromReferenceType, fromReferenceId, ... })` | Move entries from a visitor reference to the logged-in customer ([Data Functions — CRM](/backend-scripts/data-functions)) |

### `slug` (CRM entity) vs reference

**`slug`** — required on every call. This is the CRM **entity** slug from entity settings (e.g. `pattern-tracker`). It is **not** the same as `referenceType` (`customer`, `order`, …).

**`referenceType` / `referenceId`** — which record entries attach to. Omit or `null` for **`'customer'`** and the session **`customer_id`**.

```javascript theme={null}
setCrmField({ slug: 'pattern-tracker', fieldKey: 'score', value: 85 });

setCrmField({
  slug: 'pattern-tracker',
  referenceType: 'order',
  referenceId: '12345',
  fieldKey: 'followup',
  value: 'done',
});
```

Calls must use a **single options object** (no positional lists).

### Parameter types

| Property | Allowed types / notes |
| - | - |
| `slug` | entity slug string — **required**; must exist for the brand |
| `referenceType` | string (alphanumeric, `-`, `_`) or omit / `null` |
| `referenceId` | string (max 512 chars) or omit / `null` |
| `fieldKey` | string (alphanumeric, `_`, `.`, `-`) — **required** |
| `value` | string, number, boolean, or JSON object — **required** for set (`0` / `false` valid) |
| `pipelineId` / `stageId` | integer id for workflow move targets |
| `pipelineSlug` / `stageSlug` | slug string for workflow move targets |

### Moving through CRM workflow

`moveCrmToStage` and `moveCrmToPipeline` are the workflow transition functions. You can move:

* Stage to stage in the same pipeline
* Pipeline to pipeline (by setting a stage that belongs to the new pipeline)

```javascript theme={null}
moveCrmToStage({
  slug: 'pattern-tracker',
  stageSlug: 'qualified'
});

moveCrmToPipeline({
  slug: 'pattern-tracker',
  pipelineSlug: 'sales',
  stageSlug: 'proposal-sent'
});

moveCrmToPipeline({
  slug: 'pattern-tracker',
  pipelineSlug: 'sales',
  stageSlug: 'proposal-sent',
  async: true
});
```

These only change workflow placement (`pipeline_id`, `stage_id`). They do not map one field key into another.
For field mapping (for example `quiz_email -> email`), do it explicitly with reads/writes:

```javascript theme={null}
var quizEmail = getCrmField({ slug: 'pattern-tracker', fieldKey: 'quiz_email' });
if (quizEmail) {
  setCrmField({ slug: 'pattern-tracker', fieldKey: 'email', value: quizEmail, force: true });
}
```

Or move across entities in one call:

```javascript theme={null}
moveCrmToEntity({
  fromSlug: 'quiz-tracker',
  toSlug: 'sales-leads',
  fieldMap: {
    quiz_email: 'email',
    quiz_score: 'lead_score'
  },
  pipelineSlug: 'sales',
  stageSlug: 'new',
  removeFromOld: true
});

moveCrmToEntity({
  fromSlug: 'quiz-tracker',
  toSlug: 'sales-leads',
  fieldMap: { quiz_email: 'email' },
  async: true
});
```

### Input validation

All inputs are strictly validated before data is stored:

* **`slug`** must match a CRM entity configured for your brand; unknown slug → **`TypeError`**
* **`fieldKey`** must match `/^[a-zA-Z0-9_.-]+$/`
* **`referenceType`** must match `/^[a-zA-Z0-9_-]+$/`
* **`referenceId`** rejects `{}[]"\` characters
* **String values** are capped at 10,000 characters
* **Numbers** must be finite (no `NaN`, `Infinity`)
* **Objects** are JSON-serialized and capped at 10 KB
* Missing **`slug`**, **`fieldKey`**, or **`value`** (set) throws **`TypeError`**
* Other invalid inputs still cause `false` / `null` / `[]` where applicable

## Quiz / anonymous visitor → customer CRM migration

A common pattern: save a quiz or funnel payload with `setCrmField({ referenceType: 'quiz_visitor', referenceId: sessionUuid, ... })` while the visitor is anonymous, then **after members login** call `reassignCrmReference` so the same CRM entries attach to `customer` + `customer_id`. `fromReferenceId` must match `session.get('quiz_visitor_id')` and the target must be the current session customer — see **ReassignCrmReference** on the [Data Functions](/backend-scripts/data-functions) page. Clear `quiz_visitor_id` from the session after a successful migration to keep the flow idempotent.

## Security checklist

<Warning>
  **Always validate `request.body` in your backend script.** The body comes from the visitor's browser and can contain anything.
</Warning>

1. **Validate with Schema** — use the built-in [Schema validator](/backend-scripts/validation) to enforce types, lengths, and allowed values
2. **Check authentication** — verify `is_customer` before storing data
3. **Use `response.json()`** — this stops page rendering and returns JSON directly
4. **Use `response.status()`** — set proper HTTP status codes (400 for validation errors, 401 for auth)
5. **Share validation logic** — create a [backend script module](/backend-scripts/imports) for reusable schemas and auth checks

## POST body limits

| Constraint | Value |
| - | - |
| Max body size | 64 KB (larger payloads are dropped) |
| Content type | `application/json` only |
| Body available as | `request.body` (parsed object or `null`) |

## Related

* [Backend Scripts Overview](/backend-scripts/overview) — how backend scripts work, sandboxing, execution order
* [Schema Validator](/backend-scripts/validation) — full reference for the `Schema` validation API
* [Shared Modules](/backend-scripts/imports) — import/export reusable code between pages
* [Request Context](/backend-scripts/context) — `request.body`, `request.method`, and other globals
* [CRM Overview](/crm/overview) — entities, fields, pipelines, and the CRM data model


# Debug Window
Source: https://docs.elasticfunnels.io/debugging/debug-window

Advanced debugging tools for ElasticFunnels pages - monitor events, interactions, components, and performance

The Debug Window shows what is happening on an ElasticFunnels page: events, interactions, components, builders, templates, console logs, and device state.

<Note>
  The Debug Window loads asynchronously. Open it with **Ctrl + Shift + F12** (Windows/Linux) or **Command + Shift + F12** (Mac) on any ElasticFunnels page, or click **Debugger** in the top bar on any builder or code editor page.
</Note>

## Features

### 🔍 **Real-time Monitoring**

* Live page and backend event tracking
* Component discovery and interaction monitoring
* Device, viewport, and app state updates every second

### 🎯 **Interactive Debugging**

* Component highlighting and navigation
* Direct links to builder interfaces
* Console log capture and filtering

### **Page Context**

* Funnel event visualization
* Page builder and events builder shortcuts
* Export page events and debug payloads

## Getting Started

### Activating the Debug Window

1. **Open your ElasticFunnels page** in a web browser
2. **Press Ctrl + Shift + F12** (Windows/Linux) or **Command + Shift + F12** (Mac) to activate the debug window
3. **The debug window slides up** from the bottom of the screen

The debug window automatically starts monitoring your page and capturing relevant debugging information.

### How to use the Debug Window

1. **Open it** — **Ctrl + Shift + F12** (Windows/Linux) or **Command + Shift + F12** (Mac) on any ElasticFunnels page, or click **Debugger** in the top bar on a builder/code editor page.
2. **Choose a tab** — Click one of the tab buttons (Overview, Events, Page Events, Funnel, Interactions, Components, Builders, **Templates**, Console) to switch views.
3. **Use the panel**:
   * **Overview** — Quick snapshot of device, viewport, and app state (FID, Page ID, etc.).
   * **Events** — Funnel event hierarchy and flow.
   * **Page Events** — Backend page events and Script Rule results (Refresh/Clear/Export). Expand events for full context.
   * **Funnel** — How the page maps to the funnel; links to funnel builder and node.
   * **Interactions** — Tracked interactions; use focus/highlight to find elements.
   * **Components** — List of components; focus or highlight to inspect on the page; links to builders.
   * **Builders** — Shortcuts to Page Builder, Events Builder, Component Builder.
   * **Templates** — Frontend template engine: **Events** (New/Previous) for template-if results; **Pick element** then click a node to see its template bindings and child tree. See [Frontend Template Engine — Debugging](/frontend-template-engine/debugging).
   * **Console** — Captured console logs; filter by type; export.
4. **Resize** — Drag the handle at the top edge of the panel to change height. Close with the header button or press the hotkey again.

<Tip>
  From the **Page Builder** or **Page Events** UI, click **Debugger** to open the page in a new tab with the Debug Window already active—useful for testing Script Rules and page events.
</Tip>

## Debug Window Tabs

### Overview

The Overview tab provides a quick snapshot of your page's current state:

#### System Information

* **Device**: Current device type detection
* **Screen**: Browser window dimensions
* **Viewport**: Available content area
* **User Agent**: Browser information

#### App State

* **FID**: Funnel ID
* **Page ID**: Current page identifier
* **Brand ID**: Associated brand
* **Page Events**: Number of configured events
* **Interactions**: Number of tracked interactions
* **SIDs**: Session identifiers

### Events

Monitor your page's funnel events:

#### Funnel Visualization

* **Event hierarchy**: Visual representation of your funnel structure
* **Event details**: Step IDs, data, and next events
* **Event flow**: How events connect and trigger

### Page Events

Inspect backend-evaluated page events (populated by the server during the request):

* **Refresh**: Re-read the current page's backend events
* **Clear**: Clear the frontend cache of events for this page
* **Export**: Download a JSON file with the full backend debug payload
* **Status**: See whether debug is enabled, total events, event types, last event time, and the current debug key

Each event shows its type, relative time, status, and a details section. Expand "Full Context" to view the entire event payload.

#### Script Rule Debugging

The Page Events tab provides comprehensive debugging for Script Rule nodes:

**Script Rule Information Displayed:**

* **Result**: `TRUE` or `FALSE` - which path the flow took
* **Execution Time**: How long the script took to execute (milliseconds)
* **Next Path**: The branch that was followed (`true` or `false`)
* **Script Length**: Number of characters in your script
* **Used Click Data**: Whether click data was accessed
* **Used IP Whois**: Whether geolocation data was loaded
* **Has Customer Data**: Whether customer information was available
* **Device Type**: The device type during execution
* **Console Messages**: All `console.log()`, `console.warn()`, and `console.error()` output from your script
* **Errors**: Full error messages if the script failed
* **Script Preview**: First portion of your script code
* **Full Context**: Complete evaluation data with all available variables

<Tip>
  To debug Script Rules, click **"Debugger"** in the Page Builder or Page Events interface. The Debug Window will open automatically with your page, showing detailed information about each Script Rule execution, including all console output and errors in the Page Events tab.
</Tip>

**Example Use Case:**

When your Script Rule isn't working as expected:

1. Add `console.log()` statements to your script to output variable values
2. Click **"Debugger"** in the Page Builder or Page Events interface
3. The page opens with Debug Window activated
4. Go to **Page Events** tab
5. Find the `script_rule` event
6. Click "View Console Messages" to see all your logs
7. Check the "Result" to see which path was taken
8. Review "Full Context" to see all available data

### Funnel

Understand how the current page maps to your funnel:

* **Brand ID / FID / FNID**: Quick references for funnel resolution
* **Funnel Builder**: Open the funnel builder
* **Open Node**: Deep link to the node if a node code is available
* **Show Step**: Fallback deep link based on step information

<Warning>
  If the page is not part of the current funnel, you'll see a banner explaining this. In that case, the funnel flow will not trigger from this page. See [Checkout Redirect Behavior](/funnels/checkout-redirect-behavior#default-redirect-behavior).
</Warning>

### Interactions

Track user interactions and form submissions:

* **Interaction list**: All tracked interactions on the page
* **Component details**: CCID, device type, and data
* **Focus functionality**: Highlight and scroll to interaction elements
* **Real-time updates**: See interactions as they happen

```javascript theme={null}
// Focus a specific interaction element by CCID
debugWindow.focusOnElement('ccid-123');
```

### Components

Manage and debug page components:

#### Component Analysis

* **Component list**: All components with CIDs
* **Element details**: Tag names, classes, IDs
* **Position data**: X/Y coordinates and dimensions
* **Visual debugging**: Highlight components on the page

#### Component Actions

* **Focus components**: Highlight and scroll to specific components
* **Builder links**: Direct links to component builders
* **Batch highlighting**: Highlight all components simultaneously

<CodeGroup>
  ```javascript Example: Component Debugging theme={null}
  // Focus on a specific component
  debugWindow.focusComponent('hero-section-123');

  // Highlight all components
  debugWindow.highlightAllComponents();

  // Clear all highlights
  debugWindow.clearHighlights();
  ```
</CodeGroup>

### Builders

Quick access to ElasticFunnels builder interfaces:

* **Page Builder**: Direct link to edit the current page
* **Events Builder**: Configure page events and funnels
* **Component Builder**: Edit specific components
* **Page Information**: Brand ID, Page ID, and FID details

### Templates

Debug the **frontend template engine** (template-if, template-foreach, bindings):

* **Events**: "New" shows template-if results from the last scope update (which condition was chosen, or "unchanged"); "Previous" shows earlier runs. Errors from invalid conditions appear here.
* **Inspect element**: Click **Pick element**, then click any node on the page to see its template bindings (**data-condition**, **data-each**, **data-ef-text**, **data-template-value**, etc.) and a tree of its children. The panel refreshes when scope updates.

When the Templates tab is open, the template processor sends debug events to the window (no URL flag needed). For full details, see [Frontend Template Engine — Debugging](/frontend-template-engine/debugging).

### Console

Capture and monitor JavaScript console output:

* **Log capture**: Automatically captures console.log, console.warn, and console.error
* **Log filtering**: View logs by type (info, warning, error)
* **Test logging**: Generate test logs for debugging
* **Export capability**: Export logs for analysis

## Window Controls

* **Resize**: Drag the handle at the top edge of the panel to adjust height
* **Persist size**: The panel remembers its height between sessions
* **Open/Close**: Use the close button in the header, or press the hotkey again

## Usage Examples

### Debugging Page Events

1. **Open the Events tab** to see your funnel structure
2. **Review the event hierarchy** to understand the flow
3. **Check the console** for any error messages

### Testing Component Interactions

1. **Navigate to the Components tab**
2. **Click "Highlight All"** to see all tracked components
3. **Click "Focus" on specific components** to examine them
4. **Use the builder links** to edit components directly

### Exporting Debug Data

Two export options are available:

* **Header → Export**: Downloads a JSON with device info, page events, interactions, and captured console logs
* **Page Events → Export**: Downloads the backend-evaluated page events and their full contexts

## Advanced Features

### Data Export

The debug window can export comprehensive debugging data:

```javascript theme={null}
// Export debugging data
debugWindow.exportData();
```

This creates a JSON file containing:

* Page configuration
* Event data
* Interaction logs
* Console logs

## Best Practices

### Development Workflow

1. **Always test events** using the manual triggers before going live
2. **Use component highlighting** to verify tracking setup
3. **Monitor console logs** for JavaScript errors
4. **Export debug data** for troubleshooting complex issues

### Debugging Troubleshooting

1. **Check the Overview tab** for basic page information
2. **Verify event configuration** in the Events tab
3. **Ensure components are tracked** in the Components tab
4. **Review console logs** for error messages

## Troubleshooting

### Debug Window Not Appearing

* **Check keyboard shortcut**: Ensure you're pressing **Ctrl+Shift+F12** (Windows/Linux) or **Command+Shift+F12** (Mac)
* **Verify page load**: Make sure the page has fully loaded
* **Check console**: Look for any JavaScript errors

### Components Not Highlighting

* **Refresh components**: Click the "Refresh" button in the Components tab
* **Check CID attributes**: Ensure components have proper `data-cid` attributes
* **Clear and re-highlight**: Use the clear and highlight buttons

### Funnel Links Not Appearing

* **Missing brand or funnel**: Ensure `Brand ID` and `FID` are present in the Overview tab
* **No node code available**: Only “Open Node” is shown when a node code is detected; otherwise, “Show Step” is used
* **Page not in funnel**: Follow the banner link and review [Checkout Redirect Behavior](/funnels/checkout-redirect-behavior#default-redirect-behavior)

### Debug Window Opens on Wrong Domain

If you opened the Debug Window from the Page Builder and it appears on a different domain than the one you need:

<Note>
  When you preview a page or open the Debugger, it opens on the first applicable domain. If your page isn’t assigned exclusively to a specific domain, it may open on the `*.elasticfunnels.io` subdomain. This is expected behavior. To preview on another domain, manually change the page URL’s domain and reopen the Debug Window there.
</Note>

1. In the already opened Debug Window, go to the **Overview** tab and copy the **Debug Key**
2. Navigate to the actual domain you want to debug
3. Press **Ctrl + Shift + F12** (Windows/Linux) or **Command + Shift + F12** (Mac) to open the Debug Window on that domain
4. Paste the **Debug Key** when prompted to attach the session to this domain

You can find the Debug Key in the **Overview** tab of the Debug Window.

<Warning>
  The Debug Window only loads when you trigger the hotkey and does not affect page performance for visitors.
</Warning>

## Related Documentation

* [Script Rule](/funnels/script-rule) - Learn about Script Rules and how to debug them
* [Checkout Redirect Behavior](/funnels/checkout-redirect-behavior#default-redirect-behavior) - Understand default redirects and funnel assignment
* [Page Events](/funnels/page-events) - Configure page-level events
* [Create Funnel](/funnels/create-funnel) - Build and connect funnels
* [Component Tracking](/essentials/component-tracking) - Understanding component IDs


# Development & Debugging
Source: https://docs.elasticfunnels.io/debugging/overview

Advanced tools and techniques for debugging ElasticFunnels pages and optimizing performance

# Development & Debugging

Welcome to the ElasticFunnels development and debugging section. This area contains advanced tools and documentation for developers, marketers, and technical users who need to debug, optimize, and understand their ElasticFunnels implementations.

## Available Tools

<CardGroup>
  <Card title="Debug Window" icon="bug" href="/debugging/debug-window">
    Comprehensive debugging tool with real-time monitoring, event triggering, component analysis, and performance tracking. Activated with Ctrl+Shift+F12.
  </Card>
</CardGroup>

## Who Should Use These Tools

### Developers

* **Frontend developers** building custom ElasticFunnels implementations
* **JavaScript developers** working with page events and interactions
* **QA engineers** testing funnel functionality

### Marketers & Funnel Builders

* **Advanced marketers** who want to understand their funnel mechanics
* **Funnel optimizers** looking to improve performance
* **Technical marketers** troubleshooting conversion issues

### Support Teams

* **Technical support** helping customers debug issues
* **Implementation specialists** setting up complex funnels
* **Training teams** teaching advanced ElasticFunnels features

## Getting Started

The main debugging tool is the **Debug Window**, which provides:

* **Real-time monitoring** of page events and interactions
* **Visual component debugging** with highlighting and navigation
* **Performance metrics** including memory usage and load times
* **Mobile debugging** for mobile-specific issues
* **Console log capture** for JavaScript debugging
* **Direct builder links** for quick editing

<Note>
  These are advanced tools intended for development and troubleshooting. Always test thoroughly before using on production pages with real traffic.
</Note>

## Common Use Cases

### Event Debugging

* Verify funnel events are configured correctly
* Test events without user interaction
* Debug event flow and data passing

### Component Troubleshooting

* Identify components not tracking properly
* Visual debugging of component placement
* Quick access to component builders

### Performance Optimization

* Monitor memory usage during page interactions
* Track load times and performance metrics
* Identify performance bottlenecks

### Mobile Debugging

* Debug mobile-specific issues
* Test touch interactions and mobile events
* Monitor mobile device capabilities

## Best Practices

1. **Use in development environments** before deploying to production
2. **Test all events manually** before going live
3. **Monitor performance regularly** during development
4. **Export debug data** for complex troubleshooting
5. **Clear highlights** after debugging to avoid visual clutter

## Support

Need help with debugging tools or have questions about implementation?

* **Email Support**: [support@elasticfunnels.io](mailto:support@elasticfunnels.io)
* **Documentation**: Browse related guides in other sections
* **Community**: Connect with other developers and marketers

***

Ready to start debugging? Check out the [Debug Window](/debugging/debug-window) documentation for comprehensive usage instructions.


# Custom Domains & SSL
Source: https://docs.elasticfunnels.io/domains/custom-domains

Set up custom domains and SSL certificates for professional branding

Using a custom domain provides a branded URL and increases user trust through SSL encryption.

## Setup Instructions

### Step 1: Add Domain

1. Go to the "Domains" section in your dashboard
2. Click "Add Domain" and switch to "Custom Domain"
3. Enter your domain (e.g., example.com)

### Step 2: SSL Configuration

1. If you need SSL now, check "I want SSL for this domain"
2. If not, request SSL later from the domains list by clicking the options button and selecting "Request SSL" once the domain is validated

### Step 3: Merchant Association

1. Associate the domain with a merchant to automatically update buy links (e.g., Buygoods, Clickbank, Digistore24)
2. Optionally, add reCAPTCHA site and private key for collection forms

### Step 4: DNS Setup

1. Update your DNS with the required A record and TXT record for validation. Both must be added
2. You'll receive an email once validated. If you encounter issues, email support

## DNS Configuration

### Required Records

* **A Record**: Points your domain to our servers
* **TXT Record**: Validates domain ownership

### Common DNS Providers

* **Cloudflare**: DNS management with additional CDN benefits
* **GoDaddy**: Simple DNS interface for basic setup
* **Namecheap**: User-friendly DNS management
* **Google Domains**: Clean interface with Google integration

### Using Cloudflare

If your domain's DNS is on Cloudflare and the records are proxied (orange cloud), open **SSL/TLS > Overview** in Cloudflare and set the encryption mode to **Full**. Do not use **Full (strict)** or **Automatic**: with those, Cloudflare refuses the certificate on our servers and visitors see Cloudflare **error 526** instead of your pages. Traffic between Cloudflare and ElasticFunnels stays encrypted in Full mode.

If you switch the records to DNS only (grey cloud), no Cloudflare SSL setting applies and we issue the certificate for the domain ourselves.

## SSL Certificate Benefits

### Security Features

* **Encrypted Communication**: Protects user data in transit
* **Authentication**: Verifies your site's identity
* **Data Integrity**: Ensures data isn't modified during transfer

### SEO & Trust Benefits

* **Google Ranking**: SSL is a ranking factor
* **User Trust**: Browsers show security indicators
* **Conversion Boost**: Users more likely to purchase on secure sites

## Troubleshooting Common Issues

### Domain Not Validating

* Double-check DNS records are correctly entered
* Allow 24-48 hours for DNS propagation
* Verify you have access to modify DNS settings
* Contact your DNS provider if records aren't updating

### SSL Certificate Problems

* Ensure domain is fully validated before requesting SSL
* Check for mixed content issues (HTTP resources on HTTPS pages)
* Clear browser cache and cookies
* Verify all subdomains are covered by the certificate

### Cloudflare Error 526 (Invalid SSL Certificate)

Your domain is on Cloudflare with SSL/TLS set to **Full (strict)**. Change it to **Full** under **SSL/TLS > Overview** and save; the pages come back right away. We check every live domain hourly and email you if this happens.

### Buy Link Issues

* Confirm merchant association is properly configured
* Test buy links after domain setup
* Verify affiliate tracking still works with custom domain
* Check payment processor domain whitelist settings

## Best Practices

### Domain Selection

* Choose brandable, memorable domain names
* Avoid hyphens and numbers if possible
* Consider multiple domain extensions (.com, .net, etc.)
* Check trademark conflicts before purchasing

### Security Maintenance

* Enable automatic SSL renewal
* Regularly monitor certificate expiration dates
* Keep DNS records updated and documented
* Use strong authentication for domain registrar accounts

### Performance Optimization

* Use CDN services for global performance
* Enable GZIP compression at domain level
* Implement proper caching headers
* Monitor site speed and uptime regularly


# Page Customization
Source: https://docs.elasticfunnels.io/domains/customization

Customize fonts, colors, and styling to match your brand

Branding your pages consistently with the right colors and fonts strengthens your online presence.

## Colors (Theme Styles)

### Basic Setup

1. In the page builder, click the "Theme Styles" button (palette icon) on the left toolbar
2. Adjust settings like Primary, Secondary, Accent, Background, etc.
3. Choose from theme styles or enter a hex code directly
4. Save changes to apply

### Color Categories

* **Primary**: Main brand color, used for buttons and highlights
* **Secondary**: Supporting color for variety and emphasis
* **Accent**: Call-to-action elements and important highlights
* **Background**: Page and section backgrounds
* **Text**: Default text colors for readability

### Best Practices

* **Contrast**: Ensure sufficient contrast for accessibility
* **Brand Consistency**: Use your brand's official color palette
* **Psychology**: Consider color psychology for your target audience
* **Testing**: Test colors across different devices and screens

## Fonts

### Font Setup

1. Click the "Fonts" button on the toolbar (marked with "T")
2. Install new fonts if needed
3. Set the font on specific elements through the style tab

### Font Categories

* **Headings**: Bold, attention-grabbing fonts for titles
* **Body Text**: Readable fonts for content and descriptions
* **Accent**: Special fonts for quotes, highlights, or branding

### Font Selection Tips

* **Readability**: Choose fonts that are easy to read at all sizes
* **Web Safe**: Use web-safe fonts or Google Fonts for reliability
* **Brand Alignment**: Select fonts that match your brand personality
* **Loading Speed**: Limit font variations to maintain page speed

## Advanced Customization

### CSS Customization

* Custom CSS for precise control over styling
* Media queries for responsive design adjustments
* Animation and transition effects
* Custom component styling

### Brand Elements

* **Logo Placement**: Consistent logo positioning across pages
* **Color Schemes**: Seasonal or campaign-specific color variations
* **Typography Hierarchy**: Clear heading and text size relationships
* **White Space**: Proper spacing for clean, professional appearance

## Responsive Design

### Mobile Optimization

* Test appearance on different screen sizes
* Adjust font sizes for mobile readability
* Ensure buttons are touch-friendly
* Optimize images for mobile loading

### Desktop Considerations

* Utilize larger screen real estate effectively
* Maintain visual hierarchy across screen sizes
* Test on different browsers and operating systems
* Consider high-resolution displays

## Style Templates

### Creating Style Templates

* Save commonly used color/font combinations
* Apply consistent styling across multiple pages
* Share templates across team members
* Version control for style updates

### Template Categories

* **Industry-Specific**: Healthcare, finance, e-commerce styles
* **Seasonal**: Holiday and seasonal styling themes
* **Campaign**: Specific promotion or product launch styles
* **A/B Testing**: Variations for conversion optimization

## Performance Impact

### Loading Considerations

* Minimize number of font files loaded
* Use font-display: swap for better perceived performance
* Compress and optimize custom images and graphics
* Cache static styling assets

### Monitoring Tools

* Page speed testing with custom styling applied
* Cross-browser compatibility testing
* Mobile performance validation
* User experience impact assessment

## Troubleshooting

### Common Issues

* **Fonts not loading**: Check font file paths and CDN connections
* **Colors not updating**: Clear cache and hard refresh browser
* **Mobile display problems**: Test responsive breakpoints
* **Slow loading**: Optimize and compress styling assets

### Browser Compatibility

* Test across major browsers (Chrome, Firefox, Safari, Edge)
* Validate CSS for compliance with web standards
* Provide fallback fonts for unsupported custom fonts
* Test on different operating systems and devices


# reCAPTCHA Setup
Source: https://docs.elasticfunnels.io/domains/recaptcha-setup

Configure Google reCAPTCHA v3 for domain security and spam protection

reCAPTCHA v3 provides spam protection and fraud detection for your forms without interrupting user experience. This guide will walk you through setting up reCAPTCHA keys for your domains.

<Info>
  **Important**: reCAPTCHA is **only used in Collection Forms** within ElasticFunnels. This includes lead capture forms, contact forms, newsletter signups, and other collection form types. It is not used for other form types or page elements.
</Info>

## Understanding reCAPTCHA v3

### What is reCAPTCHA v3?

* **Score-based verification** - Works invisibly in the background
* **No user interaction** - No "I'm not a robot" checkboxes
* **Better user experience** - Runs in the background without adding a checkbox
* **Advanced fraud detection** - Uses machine learning to detect suspicious activity

### Benefits

* **Spam protection** - Prevents automated form submissions
* **Fraud prevention** - Detects suspicious behavior patterns
* **User-friendly** - No interruptions to legitimate users
* **Free tier** - Up to 10,000 assessments per month at no cost

## Creating reCAPTCHA Keys

### Step 1: Access Google reCAPTCHA Admin

1. Go to [Google reCAPTCHA Admin Console](https://www.google.com/recaptcha/admin/create)
2. Sign in with your Google account
3. Click **"Create"** to register a new site

### Step 2: Configure Your reCAPTCHA Site

1. **Enter a Label**:
   * Use a descriptive name like "ElasticFunnels Domains"
   * This helps you identify the site later

2. **Select reCAPTCHA Type**:
   * Choose **"Score based (v3)"**
   * This is the recommended type for no-checkbox form experience

3. **Add Domains**:
   * Click **"Add a domain"** button
   * Enter your domain (e.g., `example.com`)
   * **Important**: Add both www and non-www versions separately:
     * `example.com`
     * `www.example.com`
   * Repeat for all domains you want to protect
   * **Note**: You can use one reCAPTCHA key for all domains inside ElasticFunnels

4. **Select Google Cloud Platform Project**:
   * Choose an existing project from the dropdown
   * Or create a new project if needed
   * The project will be used for reCAPTCHA analytics and management

5. **Accept Terms**:
   * Review and accept the reCAPTCHA Terms of Service
   * Click **"Submit"** to create your site

### Step 3: Copy Your Keys

After creating your site, you'll see two keys:

1. **Site Key** (Public Key):
   * This is the public key that will be used in your frontend
   * Copy this value

2. **Secret Key** (Private Key):
   * This is the private key used for server-side verification
   * Keep this secure and never expose it publicly
   * Copy this value

## Configuring reCAPTCHA in ElasticFunnels

### Step 1: Access Domain Settings

1. Go to **Domains** in your ElasticFunnels.io dashboard
2. Find the domain you want to configure
3. Click **"Edit"** on that domain
4. Navigate to the **"Security"** tab

### Step 2: Enter Your Keys

1. **reCAPTCHA Site Key**:
   * Paste your Site Key from Google reCAPTCHA
   * This is the public key

2. **reCAPTCHA Secret Key**:
   * Paste your Secret Key from Google reCAPTCHA
   * This is the private key used for verification

3. Click **"Save"** to apply the configuration

## Important: reCAPTCHA Usage & Cost Considerations

<Warning>
  **Cost Management**: Understanding how reCAPTCHA is used and optimizing placement can help you stay within the free tier and avoid unexpected costs.
</Warning>

### Where reCAPTCHA is Used

**reCAPTCHA is only used in Collection Forms** within ElasticFunnels. This includes:

* Lead capture forms
* Contact forms
* Newsletter signups
* Other collection form types

reCAPTCHA is **not** used for other form types or page elements.

### Cost-Effective Placement

#### Recommended: Dedicated Form Pages

**Best Practice**: Place collection forms on their own dedicated pages rather than in modals or popups.

**Why this matters:**

* **Reduced API calls**: reCAPTCHA v3 makes API calls each time a form is loaded
* **Cost efficiency**: Google provides 10,000 free assessments per month, but exceeding this incurs costs
* **Better user experience**: Dedicated pages provide more space and better mobile experience
* **Lower request volume**: Forms on dedicated pages are only loaded when users navigate to them

#### Avoid: Forms in Modals

**Not Recommended**: Avoid placing collection forms (especially contact forms) in modals that appear on every page load.

**Why this is problematic:**

* **Excessive API calls**: If a contact form modal loads on every page, reCAPTCHA makes a request on every page view
* **Cost implications**: High-traffic sites can quickly exceed the free tier (10,000 assessments/month)
* **Unnecessary usage**: Users may not interact with the form, but you're still paying for assessments
* **Poor ROI**: Paying for reCAPTCHA assessments that don't result in form submissions

### Best Practice

**Use dedicated form pages** (e.g., `/contact`) instead of modal forms to avoid unnecessary reCAPTCHA API calls. This ensures reCAPTCHA assessments are only made when users actually navigate to the form page, not on every page load.

## Domain Whitelisting Best Practices

### Adding Multiple Domains

When adding domains to your reCAPTCHA site:

* **Add each domain separately**: Each domain must be explicitly listed
* **Include both www and non-www**: Add both versions:
  * `example.com`
  * `www.example.com`
* **Add all subdomains**: If you use subdomains, add them too:
  * `subdomain.example.com`
* **One key for all domains**: You can use a single reCAPTCHA key for all your ElasticFunnels domains

### Example Domain List

For a complete setup, your domain list might look like:

```
example.com
www.example.com
another-domain.com
www.another-domain.com
subdomain.example.com
```

## Troubleshooting

### Common Issues

#### reCAPTCHA Not Working

* **Verify domain is whitelisted**: Check that your domain is added in Google reCAPTCHA console
* **Check both keys**: Ensure both Site Key and Secret Key are correctly entered
* **Verify domain spelling**: Make sure the domain matches exactly (including www/non-www)
* **Check key validity**: Ensure keys haven't expired or been deleted

#### Domain Not Recognized

* **Add both www and non-www**: Google treats these as separate domains
* **Check domain format**: Use the exact domain format (no trailing slashes)
* **Wait for propagation**: Changes may take a few minutes to take effect

#### Form Submission Errors

* **Verify secret key**: Ensure the Secret Key is correctly configured
* **Check server logs**: Review error logs for reCAPTCHA verification failures
* **Test with different domains**: Verify keys work across all configured domains

### Testing Your Setup

1. **Submit a test form**: Try submitting a form on your domain
2. **Check browser console**: Look for any reCAPTCHA-related errors
3. **Verify in Google Console**: Check reCAPTCHA analytics for activity
4. **Test different domains**: Ensure all whitelisted domains work correctly

## Security Best Practices

### Key Management

* **Keep Secret Key secure**: Never expose it in client-side code
* **Rotate keys periodically**: Update keys if compromised
* **Monitor usage**: Check Google reCAPTCHA console for unusual activity
* **Document your setup**: Keep records of which domains use which keys

### Domain Security

* **Only whitelist your domains**: Don't add domains you don't control
* **Regular audits**: Review whitelisted domains periodically
* **Remove unused domains**: Clean up domains you no longer use
* **Monitor for abuse**: Watch for suspicious activity in reCAPTCHA analytics

## Advanced Configuration

### Using Multiple Keys

You can use different reCAPTCHA keys for different domains:

* **Separate keys per brand**: Use different keys for different brands
* **Testing vs Production**: Use separate keys for testing environments

### Analytics and Monitoring

* **Google reCAPTCHA Console**: Monitor requests and scores
* **Score thresholds**: Adjust verification thresholds based on your needs
* **Performance metrics**: Track reCAPTCHA impact on form submissions
* **Fraud detection**: Review suspicious activity reports

## Integration with Collection Forms

### Where reCAPTCHA is Used

reCAPTCHA is **only used in Collection Forms** within ElasticFunnels. This includes:

* **Lead capture forms**: Prevents spam submissions
* **Contact forms**: Blocks automated form filling
* **Newsletter signups**: Reduces fake email addresses
* **Custom collection forms**: Works with all collection form types

<Warning>
  reCAPTCHA is **not** used for other form types or page elements. It specifically protects collection forms that gather user data.
</Warning>

### Cost-Effective Form Placement

#### Recommended: Dedicated Form Pages

**Best Practice**: Place collection forms on their own dedicated pages rather than in modals or popups.

**Why this matters:**

* **Reduced API calls**: reCAPTCHA v3 makes API calls each time a form is loaded
* **Cost efficiency**: Google provides 10,000 free assessments per month, but exceeding this incurs costs
* **Better user experience**: Dedicated pages provide more space and better mobile experience
* **Lower request volume**: Forms on dedicated pages are only loaded when users navigate to them

#### Avoid: Forms in Modals

**Not Recommended**: Avoid placing collection forms (especially contact forms) in modals that appear on every page load.

**Why this is problematic:**

* **Excessive API calls**: If a contact form modal loads on every page, reCAPTCHA makes a request on every page view
* **Cost implications**: High-traffic sites can quickly exceed the free tier (10,000 assessments/month)
* **Unnecessary usage**: Users may not interact with the form, but you're still paying for assessments
* **Poor ROI**: Paying for reCAPTCHA assessments that don't result in form submissions

#### Example Scenarios

**✅ Good Practice:**

* Contact form on a dedicated `/contact` page
* Lead capture form on a dedicated landing page
* Newsletter signup on a dedicated `/newsletter` page
* Forms that only load when users explicitly navigate to them

**❌ Not Recommended:**

* Contact form modal that appears on every page load
* Popup forms that trigger on page entry
* Forms embedded in modals that load automatically
* Multiple forms on the same page that all load simultaneously

### User Experience

* **Invisible protection**: Users won't see any reCAPTCHA challenges
* **No interruptions**: Legitimate users experience no friction
* **Automatic verification**: Happens in the background
* **Fast processing**: Minimal impact on form submission speed

## Cost Management

### Understanding reCAPTCHA Pricing

* **Free tier**: 10,000 assessments per month at no cost
* **Paid tier**: Additional assessments are charged per 1,000 requests
* **Assessment = API call**: Each time a form loads, reCAPTCHA makes an assessment

### Optimizing Costs

1. **Use dedicated form pages**: Only load forms when users navigate to them
2. **Avoid modal forms on every page**: Don't load forms that users may never interact with
3. **Monitor usage**: Check Google reCAPTCHA console regularly for usage patterns
4. **Strategic placement**: Place forms where users are most likely to engage

### Monitoring Usage

* **Google reCAPTCHA Console**: Track your monthly assessment count
* **Set up alerts**: Configure notifications when approaching free tier limits
* **Analyze patterns**: Review which forms generate the most assessments
* **Optimize placement**: Adjust form placement based on actual usage data

<Note>
  reCAPTCHA v3 provides spam protection for Collection Forms without adding a checkbox. Remember to add both www and non-www versions of your domains, and you can use one key for all your ElasticFunnels domains. For cost-effective usage, place collection forms on dedicated pages rather than in modals that load on every page view.
</Note>


# Domain-Level Whitelisting
Source: https://docs.elasticfunnels.io/domains/whitelisting

Automatically whitelist all visitors to specific domains for domain-level content rules

Domain-level whitelisting allows you to automatically whitelist all visitors to a specific domain, ensuring they see your full content without requiring URL parameters or other conditions.

## Understanding Domain-Level Whitelisting

When you enable domain-level whitelisting, **all visitors** to that specific domain are automatically whitelisted for their entire session. This means they will see content in **Whitelisted Containers** by default, without needing query parameters or other whitelisting conditions.

### How It Works

* **Automatic whitelisting** - No URL parameters needed
* **Domain-specific** - Only applies to the configured domain
* **Session-wide** - Applies to all pages within that domain
* **Immediate effect** - Takes effect as soon as visitors land on the domain

## Setting Up Domain-Level Whitelisting

### Step 1: Access Domain Settings

1. Go to **Domains** in your ElasticFunnels.io dashboard
2. Find the domain you want to configure
3. Click **"Edit"** on that domain

### Step 2: Enable Whitelisting

1. In the domain settings, look for **"Whitelist all visitors"** option
2. **Toggle it ON** to enable automatic whitelisting
3. **Save** your domain configuration

### Step 3: Verify Configuration

* **Enabled**: All visitors to this domain will see full content
* **Disabled**: Visitors will see compliant content (unless whitelisted by other methods)

## When to Use Domain-Level Whitelisting

### Separate Domains Strategy

**Best use case**: When you have separate domains for different purposes:

* **Compliant domain** (e.g., `example-compliant.com`) - For ad platform review
* **Full content domain** (e.g., `example-full.com`) - For actual traffic

### Traffic Segmentation

Use domain-level whitelisting when you want to:

* **Direct real traffic** to a specific domain
* **Separate compliance review** from actual customer traffic
* **Simplify visitor experience** - no need for complex URL parameters
* **Ensure consistent experience** across all pages on that domain

### Campaign-Specific Domains

Perfect for:

* **VIP campaigns** with dedicated domains
* **Affiliate-specific domains** for different partners
* **Geographic targeting** with country-specific domains
* **Product-specific domains** for different offers

## Integration with Other Whitelisting Methods

### Priority Order

When multiple whitelisting methods are configured:

1. **Domain-level whitelisting** (highest priority)
2. **Query parameter whitelisting**
3. **Page event whitelisting**
4. **Default non-whitelisted state**

### Combined Strategies

You can combine domain-level whitelisting with:

* **Query parameter conditions** for additional logic
* **Page event whitelisting** for specific pages
* **Visitor segmentation** based on other criteria

## Best Practices

### Domain Organization

* **Use descriptive domain names** - Make it clear which domain serves which purpose
* **Keep domains organized** - Document which domains are whitelisted
* **Test thoroughly** - Verify whitelisting works as expected before going live
* **Monitor performance** - Track how each domain performs

### Traffic Management

* **Route traffic appropriately** - Send real visitors to whitelisted domains
* **Use non-whitelisted domains** for compliance review
* **Consider SEO impact** - Ensure proper domain strategy for search engines
* **Plan for scale** - Consider how domain strategy will work as you grow

### Security Considerations

* **Protect whitelisted domains** - Don't share whitelisted domain URLs publicly
* **Monitor access** - Keep track of who has access to whitelisted domains
* **Regular audits** - Review domain settings periodically
* **Backup strategy** - Have fallback domains if needed

## Troubleshooting

### Common Issues

* **Whitelisting not working** - Check that the toggle is enabled and saved
* **Wrong content showing** - Verify domain spelling and configuration
* **Mixed content** - Ensure all pages on the domain have proper containers
* **Session issues** - Test in incognito mode to verify fresh session behavior

### Testing Your Setup

1. **Visit the domain directly** - Should show full content immediately
2. **Check different pages** - Verify whitelisting applies site-wide
3. **Test in incognito** - Ensure it works for new visitors
4. **Verify containers** - Make sure Whitelisted Containers are displaying
5. **Test other domains** - Ensure non-whitelisted domains show compliant content

### Debugging Steps

1. **Check domain settings** - Verify the toggle is enabled
2. **Clear browser cache** - Remove any cached content
3. **Test with different browsers** - Ensure cross-browser compatibility
4. **Check page containers** - Verify Whitelisted/Non Whitelisted containers exist
5. **Review page events** - Ensure no conflicting whitelisting rules

## Advanced Configuration

### Multiple Domain Strategy

**Example setup**:

* `yoursite.com` - Non-whitelisted (for compliance)
* `yoursite-vip.com` - Whitelisted (for real traffic)
* `yoursite-affiliate.com` - Whitelisted (for affiliate traffic)

### Domain-Specific Funnels

You can create different funnels for different domains:

* **Compliant funnel** - For non-whitelisted domains
* **Full funnel** - For whitelisted domains
* **Hybrid approach** - Same funnel with different content containers

### Analytics and Tracking

* **Track domain performance** separately in analytics
* **Monitor conversion rates** for each domain
* **Compare performance** between whitelisted and non-whitelisted domains
* **Optimize based on data** from each domain

## Migration from Parameter-Based Whitelisting

### Transitioning Strategy

1. **Set up new whitelisted domain** alongside existing setup
2. **Test thoroughly** with small traffic sample
3. **Gradually redirect traffic** to new domain
4. **Monitor performance** during transition
5. **Fully migrate** once confident in new setup

### Benefits of Domain-Level Whitelisting

* **Simpler URLs** - No need for complex parameters
* **Better user experience** - Cleaner, more professional URLs
* **Easier management** - Single toggle instead of complex page events
* **Consistent behavior** - All pages on domain behave the same way

## Compliance Considerations

### Platform Policies

* **Use responsibly** - Only for legitimate compliance purposes
* **Keep compliant domains functional** - Don't make them obviously fake
* **Follow platform guidelines** - Ensure compliance with ad platform terms
* **Regular policy reviews** - Stay updated with platform policy changes

### Documentation

* **Document your strategy** - Keep records of which domains serve which purpose
* **Team training** - Ensure your team understands the domain setup
* **Change management** - Document any changes to domain configuration
* **Backup procedures** - Have contingency plans for domain issues

<Note>
  Domain-level whitelisting keeps visitor rules tied to the domain instead of scattered across page events. Use it only for clear compliance or routing needs.
</Note>


# Course Emails
Source: https://docs.elasticfunnels.io/emails/course-emails

Course enrollment, magic link, and comment notification email templates.

## Overview

Course emails are sent to students and course participants. They cover enrollment confirmations, secure login links, and engagement notifications.

## Course Enrollment

**Trigger:** Sent when a student is enrolled in a course (after purchase or manual enrollment).

**Template:** `course-enrollment`

**Key sections:**

* Indigo banner with graduation cap icon and course name
* Welcome message with student's first name
* "Open Course" CTA linking to the course login URL
* Fallback plain-text URL for email clients that don't support buttons

**Variables:**

| Variable | Description |
| - | - |
| `course.name` | Name of the course |
| `course.login_url` | Direct login URL for the course |
| `student.first_name` | Student's first name |

## Course Magic Link

**Trigger:** Sent when a student requests a magic link to sign into their course.

**Template:** `course-magic-link`

**Key sections:**

* Indigo banner with secure login messaging
* Course name in bold
* "Sign In" CTA with the magic link
* Expiration notice

**Variables:**

| Variable | Description |
| - | - |
| `course.name` | Name of the course |
| `magic_link_url` | One-time login URL |
| `student.first_name` | Student's first name |

<Warning>
  Magic links are one-time use and expire quickly. The email should be opened promptly.
</Warning>

## Course Comment Notification

**Trigger:** Sent when someone comments on a lesson the student is enrolled in.

**Template:** `course-comment-notification`

**Key sections:**

* Dark banner with lesson name
* Commenter's name and their comment in a styled blockquote
* "View Lesson" CTA

**Variables:**

| Variable | Description |
| - | - |
| `lesson.name` | Name of the lesson |
| `lesson.url` | Direct URL to the lesson |
| `commenter.name` | Name of the person who commented |
| `comment.text` | The comment content |

## Customizing course emails

Course email templates are **brand-level** templates — they're shared across all courses in your brand. To customize:

1. Navigate to **Emails** in your brand dashboard
2. Find the course template (e.g., "Course Enrollment")
3. Open in the Visual Builder or Code Editor
4. Customize the design while keeping variables intact


# Dunning
Source: https://docs.elasticfunnels.io/emails/dunning

Configure payment retry schedules, dunning emails, and callcenter escalation for failed subscription payments.

## What is dunning?

Dunning is the process of retrying failed subscription payments and communicating with customers about payment issues. ElasticFunnels automates this with configurable retry schedules and escalating email notifications.

## Retry schedule

When a subscription payment fails, ElasticFunnels automatically retries based on your configured schedule. The default schedule is:

| Attempt | Timing | Email Sent |
| - | - | - |
| 1 | Immediately | Renewal Failed (yellow — gentle) |
| 2 | 2 days later | Renewal Failed (yellow) |
| 3 | 3 days later | Renewal Failed (orange — more urgent) |
| 4 | 5 days later | Renewal Failed (orange) |
| 5 | 7 days later | Renewal Failed (red — final warning) |
| Final | 10 days later | Dunning Final Notice |

After the final notice, if payment is still unsuccessful, the subscription is automatically canceled and the [Subscription Canceled](/emails/subscription-emails#subscription-canceled) email is sent.

## Configuring the retry schedule

The retry schedule is configured in **Brand Settings > Subscriptions**. You can adjust:

* **Number of retries** — How many times to retry before canceling
* **Retry intervals** — Days between each retry attempt
* **Final grace period** — Days after the last retry before cancellation

## Escalating email urgency

The `renewal-failed` template uses the `subscription.retry_count` variable to escalate urgency:

```html theme={null}
@if(subscription.retry_count)
  @if(subscription.retry_count gte 5)
    <!-- Red: Final warning -->
    <p>Your subscription will be canceled unless you update your payment.</p>
  @elseif(subscription.retry_count gte 3)
    <!-- Orange: Getting serious -->
    <p>We've tried multiple times. Please update your card.</p>
  @else
    <!-- Yellow: First notice -->
    <p>We had trouble processing your payment. We'll try again soon.</p>
  @endif
@endif
```

## Dunning final notice

The `dunning-final` template is sent as a last resort before cancellation. It features:

* A red "Final Notice" banner
* Bold "Pending Cancellation" status
* Support contact information (phone and email from Brand Settings)
* An "Update Payment Method" CTA

## Callcenter escalation

If you have the Callcenter module enabled, failed payments can be escalated to your support team automatically. When a payment fails beyond a configurable threshold, a task is created in the callcenter queue for an agent to call the customer.

Configure escalation in **Brand Settings > Subscriptions > Callcenter Escalation**.

## Support contact in emails

The `brand.support_phone` and `brand.support_email` variables (from Brand Settings > General) are shown in dunning emails to give customers a way to resolve payment issues. Make sure these are configured before enabling dunning.

## Related

* [Subscription Emails](/emails/subscription-emails) — All subscription email templates
* [Emails & Dunning settings](/subscriptions/emails-and-dunning) — Subscription settings reference
* [Template Variables](/emails/template-variables) — Variable reference


# Login Emails
Source: https://docs.elasticfunnels.io/emails/login-emails

Member login verification code and magic link email templates.

## Overview

Login emails are sent to members accessing your members area. They provide secure authentication through verification codes or magic links.

## Verification Code

**Trigger:** Sent when a member requests a verification code to log in.

**Template:** `member-login-verification-code`

**Key sections:**

* Dark banner with lock icon
* Large monospaced verification code in a bordered card
* Expiration notice (configurable minutes)
* Security notice for unrequested codes

**Variables:**

| Variable | Description |
| - | - |
| `code` | The 6-digit verification code |
| `expires_in_minutes` | Minutes until the code expires |

The verification code is displayed in a prominent, easy-to-read format with wide letter spacing for clarity.

## Magic Link

**Trigger:** Sent when a member requests a magic link to log in.

**Template:** `member-login-magic-link`

**Key sections:**

* Dark banner with link icon
* "Access Members Area" CTA button
* Expiration notice
* Security notice for unrequested links

**Variables:**

| Variable | Description |
| - | - |
| `magic_link_url` | One-time secure login URL |
| `expires_in_minutes` | Minutes until the link expires |

<Warning>
  Magic links are single-use. Once clicked, they cannot be used again. If the link expires, the member needs to request a new one.
</Warning>

## Security considerations

* Both verification codes and magic links expire after a configurable number of minutes
* Both methods include a notice telling recipients to ignore the email if they didn't request it
* Links are single-use to prevent sharing or replay attacks

## Customizing login emails

Login templates are configured at the brand level. To customize:

1. Navigate to **Emails** in your brand dashboard
2. Find "Member Login Verification Code" or "Member Login Magic Link"
3. Edit in the Visual Builder or Code Editor
4. Keep the `{{ code }}` or `{{ magic_link_url }}` variables — removing them will break authentication


# Order Emails
Source: https://docs.elasticfunnels.io/emails/order-emails

Purchase confirmation, refund, shipping notification, and cancellation email templates.

## Overview

Order emails are sent automatically when key events happen in your store. Each email type has a corresponding system template that you can customize.

Before any of them send, the brand needs a sender and the merchant needs a template selected
in each slot. See [Sending Setup](/emails/sending-setup) for that path. A slot left empty
sends nothing, and for shipping and cancellation notices there is no warning.

## Purchase Confirmation

**Trigger:** Sent after a successful purchase. Each upsell is recorded as its own purchase,
so each one sends its own confirmation. Order bumps ride along inside the main email.

**Template:** `purchase`

**Key sections:**

* Green success banner with customer greeting
* Order details (order number, date, payment method)
* Product list with quantities and prices
* Shipping/tax/total summary with prominent total highlight
* Shipping address (if physical goods)
* Card statement descriptor note (if configured)
* "View Your Order" CTA linking to the members area

**Available variables:** All [purchase variables](/emails/template-variables#purchase-variables) and [product loop](/emails/template-variables#product-variables-inside-each).

## Refund Processed

**Trigger:** Sent when a refund is processed for an order.

**Template:** `refund`

**Key sections:**

* Blue banner confirming the refund
* Order number and refund amount (highlighted in blue)
* List of refunded items
* Info box explaining the 5–10 business day refund timeline
* Card charge name (if configured) so customers know what to look for on their statement

## Shipping Notification

**Trigger:** Sent when your fulfillment provider reports the order as shipped. Creating the
shipment is not enough on its own, the status has to change.

**Template:** `shipped`

**Key sections:**

* Teal banner with shipping confirmation
* Carrier and tracking number (if available)
* "Track Your Package" CTA linking to the tracking URL
* List of items in the package
* Shipping address

If no tracking URL is provided, the CTA falls back to "View Order Details".

## Order Cancelled

**Trigger:** Sent when an order is cancelled.

**Template:** `cancelled`

**Key sections:**

* Red banner indicating cancellation
* Order number and total
* List of cancelled items
* Refund timeline info box (if card charge name is configured)
* "Visit Our Store" CTA

## Customizing order emails

1. Navigate to **Emails** in your brand dashboard
2. Find the system template you want to customize
3. Click **Builder** (visual editor) or **Code** (HTML editor)
4. Edit the content, keeping the template variables intact
5. Save your changes

<Tip>
  System templates cannot be deleted, but you can fully customize their content and design. Changes apply to all future emails of that type.
</Tip>

<Warning>
  For purchase and refund, edit the system template in place. Duplicating it produces an
  ordinary copy, and the system template still wins even after you select the copy on the
  merchant. Shipped and cancelled always use whatever the merchant has selected.
</Warning>

## Related docs

* [Sending Setup](/emails/sending-setup) - Sender, templates, and merchant wiring
* [Emails Not Sending](/emails/troubleshooting) - Checklist when a customer got nothing
* [Template Variables](/emails/template-variables) - Complete merge tag reference


# Email Templates
Source: https://docs.elasticfunnels.io/emails/overview

Create, customize, and send branded transactional emails from ElasticFunnels.

## What are email templates?

Email templates are the transactional emails your brand sends to customers — order confirmations, shipping notifications, renewal reminders, and more. ElasticFunnels provides **system templates** for every transaction type and lets you create **custom templates** to match your brand.

## System vs custom templates

| Type | Description | Editable? |
| - | - | - |
| **System** | Auto-created when you enable a merchant or subscription feature. Covers all standard transaction types (purchase, refund, shipped, etc.) | Content and design only — cannot be deleted |
| **Custom** | Templates you create from scratch for specific use cases | Fully editable and deletable |

System templates are marked with a **Locked** badge in the email list.

## Two ways to edit

After creating or opening an email template, you can choose between two editors:

### Visual Builder (GrapesJS)

A drag-and-drop editor that lets you design emails visually. Ideal for non-technical users who want to build responsive emails without writing HTML.

* Drag blocks like text, images, buttons, and dividers
* Style elements with a visual properties panel
* Preview desktop and mobile layouts side by side
* Insert template variables from the Variables panel

### Code Editor (Monaco)

A full HTML code editor for users who prefer writing markup directly. The code editor gives you complete control over the email HTML.

* Syntax highlighting for HTML/CSS
* Auto-completion and error detection
* Save with `Cmd+S` / `Ctrl+S`
* Switch to the Visual Builder at any time

## Template variables

Every email template has access to **variables** — dynamic data that gets replaced when the email is sent. For example, `{{ purchase.customer_first_name }}` is replaced with the customer's actual first name.

Variables are organized by **scope** (purchase, subscription, brand, etc.). See the [Template Variables](/emails/template-variables) reference for the complete list.

## Conditional content

Use `@if` / `@endif` directives to show or hide sections based on available data:

```html theme={null}
@if(purchase.tracking_url)
<a href="{{ purchase.tracking_url }}">Track Your Package</a>
@endif
```

Use `@each` / `@endeach` to loop over collections like products:

```html theme={null}
@each(product in products)
<p>{{ product.name }} — ${{ product.total }}</p>
@endeach
```

## Related docs

* [Sending Setup](/emails/sending-setup) - Connect a sender and wire templates to a merchant
* [Template Variables](/emails/template-variables) — Complete variable reference
* [Order Emails](/emails/order-emails) — Purchase, refund, shipped, cancelled
* [Subscription Emails](/emails/subscription-emails) — Renewals, paused, canceled, dunning
* [Course Emails](/emails/course-emails) — Enrollment, magic links, comments
* [Login Emails](/emails/login-emails) — Verification codes and magic links
* [Emails Not Sending](/emails/troubleshooting) - Checklist when a customer got nothing


# Sending Setup
Source: https://docs.elasticfunnels.io/emails/sending-setup

Connect a sender, wire templates to a merchant, and send a test before your first real order.

## Three things have to be true

An order confirmation only reaches a customer when all three of these are in place:

1. **A sender.** SMTP credentials on the brand, or an email integration on the merchant.
2. **A template.** The email itself, from **Emails** in your brand dashboard.
3. **That template selected on the merchant.** Merchant → **Email** tab → **Order Emails**.

Miss any one of them and nothing sends. There is no built-in fallback email, and for
shipping and cancellation notices there is no warning either. The order goes through, the
customer is charged, and the inbox stays empty.

<Warning>
  ElasticFunnels never sends a generic default on your behalf. If the slot is empty, the
  customer gets no email at all.
</Warning>

***

## Step 1: connect a sender

Go to **Settings** → **Emailing**. This is the SMTP relay ElasticFunnels connects to for
every transactional email this brand sends.

<Steps>
  <Step title="Enter the server details">
    Your email provider gives you these. This example uses Mailgun:

    | Field | Value | Notes |
    | - | - | - |
    | SMTP host | `smtp.mailgun.org` | From your provider's SMTP page |
    | Port | `587` | 587 for TLS, 465 for SSL, 25 unencrypted |
    | Encryption | `TLS` | Match the port |
    | Username | `team@example.com` | Usually the full mailbox address, not your provider login |
    | Password | The SMTP password | Stored encrypted. Leave blank on later saves to keep it |

    Mailgun, Postmark, Amazon SES, SendGrid, Gmail, and any other relay that speaks SMTP all
    work here.
  </Step>

  <Step title="Set the sender identity">
    This is what the customer sees in their inbox:

    | Field | Example | What it does |
    | - | - | - |
    | From name | `Acme Health Team` | The display name on the message |
    | From email | `team@example.com` | Must be on a domain your provider is allowed to send for |
    | Reply-to email | `support@example.com` | Where customer replies land |

    Set **Reply-to** to a mailbox someone reads. Customers reply to order emails constantly,
    asking to change an address or cancel. Leave it blank and their replies go to the From
    address instead, which is often an unmonitored sending mailbox.
  </Step>

  <Step title="Save, then send a test">
    **Save SMTP**, then **Send test**. The test message goes to the email address of the user
    who is logged in, not to the From address.

    If it arrives, the card shows a green **Verified** badge.
  </Step>
</Steps>

<Note>
  **"Verified" means one test message was accepted by your SMTP server.** It is not domain
  verification. It does not check SPF, DKIM, or DMARC, and it does not confirm your provider
  will accept the From address you entered. Send a real test order before you trust it.
</Note>

### The From address on the template is ignored

Email templates have their own `from_name`, `from_email`, and `reply_to_email` fields. When
the brand sends over SMTP, those are not used. The three values on the **Emailing** tab win
for every template. Change the sender in one place and every transactional email follows.

### Alternative: a per-merchant email integration

Instead of brand SMTP, a merchant can carry its own sending service. Merchant → **Email**
tab → **Email Integration** lists your Mailgun, SendGrid, and Mailrelay integrations from
**Integrations**.

**Brand SMTP takes priority.** If the brand has SMTP configured, the merchant integration
is ignored for order emails. Use the merchant integration when a single brand sells through
merchants that need to mail from different providers.

***

## Step 2: create the templates

Open **Emails** in the brand dashboard. Every brand ships with system templates for the
standard transaction types, and you can create your own. See
[Email Templates](/emails/overview) for the builder and
[Template Variables](/emails/template-variables) for the merge tags.

The fastest route is Step 3: the merchant screen can create a pre-built template and select
it in one click.

***

## Step 3: wire the templates to the merchant

Go to **Merchants**, open the merchant, and switch to the **Email** tab. This is the step
people miss.

Templates live on the brand. Sending is decided per merchant. A brand with three merchants
has three separate sets of these slots, and filling them in for one does nothing for the
other two.

### Order Emails

| Slot | Fires when |
| - | - |
| New Purchase | A purchase conversion is recorded, including every upsell |
| Refund | A refund is processed, from the gateway or from ElasticFunnels |
| Order Shipped | Fulfillment reports the order as shipped and a tracking number arrives |
| Order Cancelled | A cancellation is recorded for the order |

### Subscription Emails

Visible for NMI and Stripe merchants:

| Slot | Fires when |
| - | - |
| Renewal Success | A rebill is charged successfully |
| Renewal Failed | A rebill is declined. The template escalates by retry count |
| Pre-Renewal Reminder | 3 days before the next charge, from a daily job |
| Subscription Paused | A subscription is paused |
| Subscription Canceled | A subscription is canceled |

Each row has a **Create template** button that seeds a ready-made template for that type and
selects it immediately. A row showing **Not set** sends nothing.

<Tip>
  The usual setup is all four order slots filled on the merchant, with a custom purchase
  template rather than the stock one. Create from the button, then edit the copy in the
  builder.
</Tip>

### Which template actually gets used

There are two places a subscription template can be chosen, and they are checked in order:

1. The merchant's **Email** tab. This wins.
2. **Settings** → **Subscriptions**, which holds brand-wide defaults for the same events.
3. The brand's built-in system template for that event.

Order emails are simpler. Set them on the merchant. The brand defaults under
**Settings** → **Subscriptions** are not a reliable fallback for shipping and cancellation
notices, and purchase and refund prefer the brand's locked system template over anything
picked in a dropdown. If you want different purchase copy, edit the locked template rather
than duplicating it.

***

## What sends, and from where

Order emails are queued and sent by ElasticFunnels a couple of seconds after the conversion
lands, so Elasticsearch has time to index the line items. Members area login codes are sent
directly by the page runtime and arrive immediately.

| Email | Triggered by |
| - | - |
| New purchase | The gateway postback for a purchase conversion |
| Upsell purchase | Each upsell is its own conversion, so each one sends its own email |
| Order bump | No separate email. Bump lines appear inside the purchase email |
| Refund | A refund postback, or a refund issued inside ElasticFunnels |
| Order shipped | The fulfillment provider flipping the order to shipped |
| Order cancelled | A cancellation postback |
| Renewal success and failure | The rebill result posted back from the gateway |
| Pre-renewal reminder | A scheduled daily job |
| Members area login code and magic link | The customer requesting one on your site |

***

## Deliverability

The SMTP form gets the message to your provider. Getting it to the inbox is your provider's
job, and it depends on DNS records you set once:

* **SPF and DKIM** for the sending domain, at your email provider. Every provider documents
  the exact records. Without them, order confirmations land in spam or get rejected.
* **A From address on a domain your provider is authorised to send for.** `team@example.com`
  only works once `example.com` is added and verified as a sending domain at your provider.
* **A real reply-to mailbox.** Providers score unmonitored senders poorly, and customers who
  cannot reach you open chargebacks instead.

Use a subdomain for transactional mail if you also send marketing campaigns. A complaint on
a promotional blast should not put order confirmations at risk.

***

## Related docs

* [Order Emails](/emails/order-emails) - What each order email contains
* [Subscription Emails](/emails/subscription-emails) - Renewals, paused, canceled, dunning
* [Emails Not Sending](/emails/troubleshooting) - Checklist when a customer got nothing
* [Template Variables](/emails/template-variables) - Complete merge tag reference
* [Email Marketing Integrations](/integrations/email-marketing) - Mailgun, SendGrid, generic SMTP


# Subscription Emails
Source: https://docs.elasticfunnels.io/emails/subscription-emails

Renewal, pre-renewal, paused, canceled, payment expiring, and dunning email templates.

## Overview

Subscription emails keep customers informed about their recurring billing status. They cover the full lifecycle: successful renewals, upcoming charges, payment issues, paused/canceled states, and dunning.

## Renewal Success

**Trigger:** Sent after a successful subscription renewal charge.

**Template:** `renewal-success`

**Key sections:**

* Green success banner
* Order details (order number, date, billing cycle number, next charge date)
* Product list with totals
* Card statement descriptor note

## Renewal Failed

**Trigger:** Sent when a subscription renewal payment fails.

**Template:** `renewal-failed`

This template uses **escalating urgency** based on the retry count:

| Retry Count | Banner Color | Heading |
| - | - | - |
| 1–2 | Yellow | "We had trouble with your payment" |
| 3–4 | Orange | "Your payment could not be processed" |
| 5+ | Red | "Your subscription will be canceled" |

The body text also escalates, becoming more urgent with each retry. The template includes:

* Subscription details (product, amount, card on file, next retry date)
* Support contact box with phone and email
* "Update Payment Method" CTA

Use the `subscription.retry_count` variable with `@if` directives to customize urgency levels further.

## Pre-Renewal Reminder

**Trigger:** Sent 3 days before an upcoming subscription renewal.

**Template:** `pre-renewal`

**Key sections:**

* Indigo banner with bell icon
* Subscription details (product, amount, charge date)
* Product list
* "Manage Subscription" CTA

## Subscription Paused

**Trigger:** Sent when a subscription is paused.

**Template:** `subscription-paused`

**Key sections:**

* Amber banner with pause icon
* Product name and resume date (or "No date set")
* "Resume Subscription" CTA

## Subscription Canceled

**Trigger:** Sent when a subscription is canceled.

**Template:** `subscription-canceled`

**Key sections:**

* Red banner
* Product and order details
* "We're sorry to see you go" message with green reactivation CTA
* Encourages the customer to return

## Payment Method Expiring

**Trigger:** Sent when a customer's card on file is about to expire.

**Template:** `payment-method-expiring`

**Key sections:**

* Orange banner with credit card icon
* Card details (last 4 digits, expiration date highlighted in orange)
* Next charge date
* Support contact box (amber) explaining how to update payment
* "Manage Subscription" CTA

## Dunning Final Notice

**Trigger:** Sent as the last dunning attempt before subscription cancellation.

**Template:** `dunning-final`

For a deep dive on dunning configuration, see [Dunning](/emails/dunning).

**Key sections:**

* Red banner with warning icon
* Amount due and card on file
* "Pending Cancellation" status in red
* Support contact box (red) with instructions
* "Update Payment Method" CTA

## Configuring subscription emails

Subscription email templates are chosen in two places, checked in this order:

1. **Merchants** -> open the merchant -> **Email** tab -> **Subscription Emails**. This wins.
2. **Settings** -> **Subscriptions**, which holds brand-wide defaults for the same events.
3. The brand's built-in system template for that event.

A merchant with an empty slot and no brand default still sends, using the system template.
Subscription slots only appear for merchants that bill recurring charges through
ElasticFunnels (NMI and Stripe).

Nothing sends until the brand has a sender configured. See [Sending Setup](/emails/sending-setup).

See also: [Emails & Dunning settings](/subscriptions/emails-and-dunning) and
[Emails Not Sending](/emails/troubleshooting)


# Template Variables
Source: https://docs.elasticfunnels.io/emails/template-variables

Complete reference for all email template variables available in ElasticFunnels.

## How variables work

Template variables use double curly braces: `{{ variable.path }}`. When an email is sent, each variable is replaced with the actual value from the transaction.

Variables are grouped by **scope** — each email type has access to different scopes depending on the data available at send time.

## Brand variables (all emails)

Every email template has access to these brand-level variables:

| Variable | Example | Description |
| - | - | - |
| `brand_name` | Acme Health | Your brand name |
| `current_year` | 2026 | Current year (for copyright footers) |
| `brand.support_email` | [support@example.com](mailto:support@example.com) | Support email from Brand Settings |
| `brand.support_phone` | +1 800 555 0100 | Support phone from Brand Settings |

## Purchase variables

Available in: purchase, refund, shipped, cancelled, renewal-success, renewal-failed, pre-renewal, subscription-paused, subscription-canceled, payment-method-expiring, dunning-final.

| Variable | Example | Description |
| - | - | - |
| `purchase.customer_email` | [jane@example.com](mailto:jane@example.com) | Customer email |
| `purchase.customer_name` | Jane Smith | Full name |
| `purchase.customer_first_name` | Jane | First name |
| `purchase.customer_last_name` | Smith | Last name |
| `purchase.customer_phone` | +1 555 0100 | Phone number |
| `purchase.public_order_id` | ORD-1234 | Public order number |
| `purchase.total` | 99.00 | Order total |
| `purchase.total_shipping_cost` | 5.99 | Shipping cost |
| `purchase.total_taxes` | 8.50 | Tax amount |
| `purchase.currency_code` | USD | Currency |
| `purchase.purchased_at` | Apr 28, 2026 | Formatted order date |
| `purchase.purchased_at_time` | 3:45 PM | Formatted order time |
| `purchase.payment_method` | Visa ending in 4242 | Payment method |
| `purchase.tracking_number` | 1Z999AA10123456784 | Tracking number |
| `purchase.tracking_url` | https\://... | Tracking URL |
| `purchase.carrier` | UPS | Shipping carrier |
| `purchase.domain` | shop.example.com | Purchase domain |
| `purchase.card_charge_name` | ACME HEALTH | Statement descriptor |

### Shipping / billing address fields

| Variable | Description |
| - | - |
| `purchase.shipping_address` | Street address |
| `purchase.shipping_city` | City |
| `purchase.shipping_state` | State / province |
| `purchase.shipping_zip` | Postal code |
| `purchase.shipping_country` | Country |
| `purchase.billing_address` | Billing street |
| `purchase.billing_city` | Billing city |
| `purchase.billing_state` | Billing state |
| `purchase.billing_zip` | Billing postal code |
| `purchase.billing_country` | Billing country |

## Product variables (inside `@each`)

Available inside `@each(product in products)` loops:

| Variable | Example | Description |
| - | - | - |
| `product.name` | Monthly Membership | Product display name |
| `product.product_sku` | SKU-001 | Product SKU |
| `product.price` | 49.99 | Unit price |
| `product.quantity` | 1 | Quantity |
| `product.total` | 49.99 | Line total |
| `product.currency_code` | USD | Currency |
| `product.image_url` | https\://... | Product image |

## Subscription variables

Available in subscription-related emails (renewal-success, renewal-failed, pre-renewal, subscription-paused, subscription-canceled, payment-method-expiring, dunning-final):

| Variable | Example | Description |
| - | - | - |
| `subscription.product_name` | Monthly Membership | Subscription product |
| `subscription.amount` | 49.99 | Recurring amount |
| `subscription.cycle_number` | 3 | Current billing cycle |
| `subscription.next_charge_date` | 2026-05-01 | Next charge date |
| `subscription.next_retry_date` | 2026-05-03 | Next retry date (failed payments) |
| `subscription.card_last4` | 4242 | Last 4 digits of card |
| `subscription.card_exp` | 12/2026 | Card expiration |
| `subscription.resume_date` | 2026-06-01 | Resume date (paused subscriptions) |
| `subscription.retry_count` | 3 | Number of failed payment retries |

## Course variables

Available in course enrollment, course magic link, and course comment notification emails:

| Variable | Example | Description |
| - | - | - |
| `course.name` | Marketing 101 | Course name |
| `course.login_url` | https\://... | Course login URL |
| `student.first_name` | Jane | Student first name |
| `lesson.name` | Lesson 3: Funnels | Lesson name |
| `lesson.url` | https\://... | Lesson URL |
| `commenter.name` | John | Comment author name |
| `comment.text` | Great lesson! | Comment content |

## Login variables

Available in member login verification code and magic link emails:

| Variable | Example | Description |
| - | - | - |
| `code` | 482910 | Verification code |
| `magic_link_url` | https\://... | Magic link URL |
| `expires_in_minutes` | 15 | Expiration time |

## Refund request variables

Available in the refund request received email:

Uses `purchase.*` variables (see above) plus `brand.support_email` and `brand.support_phone`.


# Emails Not Sending
Source: https://docs.elasticfunnels.io/emails/troubleshooting

A checklist for when a customer did not receive an order, refund, shipping, or renewal email.

## Start with the send log

Open **Email Send Logs** at `/{brand}/emails/smtp-logs`. It records every email sent through
your brand's SMTP configuration, with the recipient, the subject, the template used, the
source that triggered it, and whether it was delivered or failed.

Filter by **Source** to see one type at a time. `Purchase` and `Refund` are the order jobs,
`Members Login` is the members area, `SMTP Test` is the button on the Emailing tab.

Two different answers, two different problems:

* **The send is listed and failed.** Your credentials or your provider are the issue. Go to
  [Sender problems](#sender-problems).
* **The send is not listed at all.** Nothing was ever attempted. Go to
  [The email was never triggered](#the-email-was-never-triggered).

<Note>
  The log covers the SMTP path. Merchants sending through a Mailgun or SendGrid integration
  instead of brand SMTP write to a separate log and will not appear here.
</Note>

***

## The email was never triggered

Work down this list in order. The first miss is almost always the answer.

<Steps>
  <Step title="Is the slot filled on the right merchant?">
    Merchant → **Email** tab. A row showing **Not set** sends nothing, ever.

    This is the most common cause by a wide margin. Templates belong to the brand, but the
    choice of which one to send belongs to each merchant. Adding a merchant, or switching an
    offer to a different merchant, leaves you with a fresh set of empty slots.
  </Step>

  <Step title="Does the order have a customer email?">
    Open the conversion. If the email field is empty, every email for that order is skipped
    silently. Abandon records from some gateways carry no customer data at all, so they can
    never resolve into a confirmation email.
  </Step>

  <Step title="Is a sender configured?">
    **Settings** → **Emailing** needs SMTP credentials, or the merchant needs an **Email
    Integration**. With neither, the job fails on every attempt.

    Check **Brand Actions** on your dashboard. Missing templates and missing integrations raise
    a task there for purchase and subscription emails.
  </Step>

  <Step title="For shipping emails, did fulfillment actually report shipped?">
    The Order Shipped email fires when the fulfillment provider flips the order to shipped, not
    when you create the shipment. No status change means no email. Check the order's fulfillment
    status and tracking number first.
  </Step>

  <Step title="For renewal emails, is the merchant on NMI or Stripe?">
    Subscription email slots only exist for merchants that bill recurring charges through
    ElasticFunnels. Other gateways have no subscription section on the Email tab.
  </Step>
</Steps>

<Warning>
  **Shipping and cancellation emails fail quietly.** Purchase and subscription emails raise a
  Brand Action when they cannot send. Order Shipped and Order Cancelled do not. If those two
  slots are empty, there is no warning anywhere in the app. Check them by eye.
</Warning>

***

## Sender problems

The send is in the log with a **Failed** status.

| Symptom | Cause | Fix |
| - | - | - |
| Authentication failed | Wrong username or password | The username is usually the full mailbox address your provider issued, not your account login |
| Connection refused or timeout | Port and encryption do not match | 587 with TLS, 465 with SSL. Check your provider's SMTP page |
| Sender address rejected | The From domain is not authorised at your provider | Add and verify the sending domain with the provider, then retry |
| Delivered but landing in spam | SPF and DKIM missing | Add the DNS records your provider specifies for the sending domain |
| Customer replies vanish | Reply-to is blank | Set **Reply-to email** to a monitored mailbox |

<Note>
  The green **Verified** badge only means one test message was accepted by your SMTP server.
  It does not check SPF, DKIM, DMARC, or whether your provider will accept your From address
  on real volume. A brand can be Verified and still land in spam.
</Note>

***

## Known limitations

These are current behaviours worth knowing before you spend an hour debugging.

<AccordionGroup>
  <Accordion title="I edited a copy of the purchase template, but the old one still sends">
    Purchase and refund emails prefer your brand's built-in system template over whatever is
    selected in the merchant dropdown. Duplicating a system template produces an ordinary copy,
    so selecting that copy on the merchant has no effect while the system template still exists.

    Edit the system template directly. It is marked with a **Locked** badge in the Emails list.
    Its content and design are fully editable, it just cannot be deleted.

    This applies to purchase and refund only. Shipped and cancelled always use the merchant
    dropdown.
  </Accordion>

  <Accordion title="Resending an email from a conversion says the merchant has no email integration">
    The manual resend action requires a merchant **Email Integration**, even when the brand is
    sending fine over SMTP. Automatic sends are unaffected. To resend on an SMTP-only brand, add
    an email integration to the merchant.
  </Accordion>

  <Accordion title="Send test inside the email builder does nothing on an SMTP-only brand">
    The **Send test** button on a template needs a Mailgun, SendGrid, or Mailrelay integration.
    It does not use brand SMTP. The **Send test** button on **Settings** → **Emailing** does use
    SMTP, so use that one to confirm the sender, and a real test order to confirm the template.
  </Accordion>

  <Accordion title="Pre-renewal reminders never arrive on an SMTP-only brand">
    The pre-renewal job checks for a merchant **Email Integration** specifically, so brand SMTP
    alone is not enough for that one email. Other subscription emails work over SMTP normally.
    Add an email integration to the merchant if you need pre-renewal reminders.
  </Accordion>

  <Accordion title="A template renders with blank fields">
    Each template is written for one scope. A subscription template dropped into the Shipped slot
    renders with empty subscription values and no error, because the shipping context carries no
    subscription data. The merchant dropdowns list every template on the brand, so nothing stops
    the mismatch.

    Match the template to the slot, and check the scope in
    [Template Variables](/emails/template-variables).
  </Accordion>

  <Accordion title="Support phone and email are missing from the footer">
    Seeded templates print the support block only when the brand has those values set. Add them
    in **Settings** under your brand variables and they appear on the next send.
  </Accordion>
</AccordionGroup>

***

## Nothing at all is sending, for any brand

Order emails are queued. If the email queue worker is stopped, every send waits in the queue
and nothing surfaces in the interface. The send log stays empty because no attempt is ever
made. If several brands go quiet at the same moment, this is the first thing to check with
your administrator.

***

## Related docs

* [Sending Setup](/emails/sending-setup) - Sender, templates, and merchant wiring
* [Order Emails](/emails/order-emails) - What each order email contains
* [Subscription Emails](/emails/subscription-emails) - Renewals, paused, canceled, dunning
* [Dunning](/emails/dunning) - Retry schedule and escalation


# Brand Actions & Alerts
Source: https://docs.elasticfunnels.io/essentials/brand-actions

Automated suggestions and alerts to optimize your brand's performance, costs, and data quality

Brand Actions provide automated suggestions and alerts to help you optimize your brand's performance, reduce costs, improve data quality, and maintain your site's health. The system continuously monitors your brand and generates actionable recommendations that you can review and apply.

<Note>
  Brand Actions appear as notifications in your dashboard and are sent via email when they require your attention. You can review, preview, and apply these actions safely with built-in protection against bulk changes.
</Note>

## How Brand Actions Work

### 1. **Automatic Detection**

The system continuously monitors your brand for:

* Cost optimization opportunities
* Data quality issues
* SEO improvement suggestions
* Buy link problems
* Reconciliation discrepancies

### 2. **Smart Suggestions**

When issues are detected, the system creates actionable suggestions with:

* Clear descriptions of the problem
* Recommended solutions
* Preview of changes before applying
* Impact estimates and safety warnings

### 3. **Safe Application**

Before making any changes, you can:

* Preview exactly what will be changed
* See before/after comparisons
* Review safety warnings for bulk operations
* Apply changes with confidence

## Types of Brand Actions

### 🔧 **Cost Optimization**

Identify opportunities to reduce costs and improve profitability:

#### Shipping Cost Adjustments

* **Alert**: "Product shipping costs are outdated based on recent fulfillment data"
* **Action**: Update average shipping costs to reflect current fulfillment costs
* **Impact**: Improve profit margin calculations and pricing accuracy

#### COGS (Cost of Goods Sold) Updates

* **Alert**: "Cost of goods sold doesn't match fulfillment provider data"
* **Action**: Adjust COGS based on actual fulfillment costs
* **Impact**: More accurate profitability reporting and pricing decisions

#### Price Optimization

* **Alert**: "Product prices may be suboptimal based on market analysis"
* **Action**: Suggest price adjustments for better conversion rates
* **Impact**: Improve revenue per visitor and overall profitability

### 📊 **Data Quality**

Ensure your product and page data is accurate and complete:

#### Missing Product Information

* **Alert**: "Products are missing essential information (descriptions, images, categories)"
* **Action**: Add missing product details to improve catalog quality
* **Impact**: Better user experience and improved conversion rates

#### SKU Standardization

* **Alert**: "Product SKUs are inconsistent across different systems"
* **Action**: Standardize SKU formats for better inventory management
* **Impact**: Reduced order fulfillment errors and improved tracking

#### Duplicate Product Detection

* **Alert**: "Potential duplicate products detected in your catalog"
* **Action**: Merge or remove duplicate products
* **Impact**: Cleaner product catalog and reduced customer confusion

### 🔗 **Buy Link Issues**

Monitor and fix problems with your purchase links:

#### Broken Buy Links

* **Alert**: "Buy links are returning errors or leading to broken pages"
* **Action**: Update or fix broken purchase links
* **Impact**: Prevent lost sales and improve customer experience

#### Missing Buy Links

* **Alert**: "Products don't have associated buy links for purchasing"
* **Action**: Add buy links to enable product purchases
* **Impact**: Enable sales for products that weren't generating revenue

#### Buy Link Optimization

* **Alert**: "Buy links may not be optimized for best conversion rates"
* **Action**: Optimize buy link configurations and parameters
* **Impact**: Improve conversion rates and reduce cart abandonment

### 📈 **SEO Improvements**

Enhance your site's search engine visibility:

#### Missing Meta Tags

* **Alert**: "Pages are missing important SEO meta tags"
* **Action**: Add meta titles, descriptions, and keywords
* **Impact**: Better search engine rankings and click-through rates

#### Page Speed Issues

* **Alert**: "Pages are loading slowly and may hurt SEO rankings"
* **Action**: Optimize images, scripts, and page elements
* **Impact**: Improved search rankings and user experience

#### Content Optimization

* **Alert**: "Page content could be optimized for better search performance"
* **Action**: Improve content structure, headings, and keyword usage
* **Impact**: Higher search engine rankings and organic traffic

### 🔄 **Reconciliation Alerts**

Identify and resolve discrepancies between your ElasticFunnels data and fulfillment providers:

#### Fulfillment Cost Discrepancies

* **Alert**: "Fulfillment costs in ElasticFunnels don't match your provider's data"
* **Action**: Update fulfillment costs to match actual provider charges
* **Impact**: Accurate profit calculations and pricing decisions

#### Order Data Mismatches

* **Alert**: "Order information doesn't match between systems"
* **Action**: Reconcile order data to ensure accurate reporting
* **Impact**: Better order tracking and customer service

#### Inventory Sync Issues

* **Alert**: "Product inventory levels are out of sync with fulfillment provider"
* **Action**: Synchronize inventory levels across systems
* **Impact**: Prevent overselling and improve order fulfillment

## User Experience & Safety Features

### Action Notifications

#### Dashboard Alerts

* **Action Badge**: Star icon with number of pending actions
* **Priority Color Coding**:
  * 🔴 Red: Critical/High priority actions
  * 🟡 Yellow: Medium priority actions
  * 🔵 Blue: Low priority actions
* **Quick Preview**: Hover to see action details without opening modal

#### Email Notifications

* **Immediate Alerts**: Sent when critical actions are detected
* **Daily Summaries**: Digest of pending actions requiring attention
* **Reminder Emails**: Follow-up notifications for unresolved actions

### Action Review Process

#### 1. **Action Details**

When you click on an action, you'll see:

* **Clear Description**: What the issue is and why it needs attention
* **Recommended Solution**: Specific actions to resolve the problem
* **Impact Assessment**: How the change will affect your business
* **Priority Level**: How urgent the action is

#### 2. **Preview Changes**

Before applying any action, you can:

* **See Exact Changes**: Before/after comparison of what will be modified
* **Review Affected Records**: Complete list of items that will be changed
* **Understand Impact**: Number of records affected and scope of changes

#### 3. **Safety Warnings**

The system provides multiple levels of protection:

**Safe Operations (Blue)**

* Affects fewer than 10 records
* Normal operation indicators
* Standard apply button

**Bulk Operations (Yellow)**

* Affects 10-99 records
* Warning message: "This action will affect X records. Please verify this is intentional."
* Proceed with caution indicators

**Critical Operations (Red)**

* Affects 100+ records
* **Danger Warning**: "This is a bulk operation that could cause significant data changes."
* **Mandatory Confirmation**: Must check "I understand this is a dangerous operation" to proceed
* **Red Apply Button**: Visual indicator of dangerous operation

### Input Forms & Customization

Many actions allow you to customize the solution:

#### Text Input Actions

* **Product Names**: Update product titles and descriptions
* **SKU Corrections**: Fix product SKU formatting
* **URL Updates**: Correct buy link URLs

#### Numeric Input Actions

* **Price Adjustments**: Set new product prices
* **Cost Updates**: Adjust shipping costs and COGS
* **Inventory Levels**: Update stock quantities

#### Selection Actions

* **Category Changes**: Choose from predefined product categories
* **Status Updates**: Change product or page status
* **Priority Assignments**: Set action priority levels

### Action Resolution

#### Apply Actions

* **Single Action**: Apply individual actions after review
* **Bulk Actions**: Apply multiple related actions at once
* **Immediate Effect**: Changes take effect immediately
* **Confirmation**: Success notification with summary of changes

#### Decline Actions

* **Reason Tracking**: System tracks why actions were declined
* **No Changes**: Declining an action makes no changes to your data
* **Future Prevention**: System learns from declined actions

## Action Categories in Detail

### Cost Optimization Actions

**Product Pricing Analysis**

* Identifies products with suboptimal pricing
* Suggests price adjustments based on conversion data
* Compares pricing with market standards
* Recommends A/B testing for price optimization

**Shipping Cost Updates**

* Compares your set shipping costs with actual fulfillment costs
* Identifies products with outdated shipping calculations
* Suggests adjustments to improve profit margins
* Alerts when shipping costs significantly impact profitability

**COGS Reconciliation**

* Compares your cost of goods sold with fulfillment provider data
* Identifies discrepancies in product costs
* Suggests corrections to improve profit reporting
* Alerts when COGS changes affect pricing strategy

### Data Quality Actions

**Product Information Completeness**

* Identifies products missing essential information
* Suggests adding descriptions, images, and specifications
* Recommends category assignments for better organization
* Alerts when incomplete products affect user experience

**Data Consistency Checks**

* Finds inconsistencies in product data across systems
* Suggests standardization of formats and values
* Recommends cleanup of duplicate or outdated information
* Alerts when data inconsistencies affect operations

### SEO & Performance Actions

**Meta Tag Optimization**

* Identifies pages missing SEO meta tags
* Suggests optimized titles and descriptions
* Recommends keyword improvements
* Alerts when SEO issues affect search rankings

**Page Performance Issues**

* Identifies slow-loading pages
* Suggests image optimization and script improvements
* Recommends performance enhancements
* Alerts when performance issues affect user experience

### Buy Link Monitoring

**Link Functionality Checks**

* Monitors buy links for errors and broken connections
* Identifies links leading to incorrect pages
* Suggests corrections for non-functional links
* Alerts when broken links affect sales

**Conversion Optimization**

* Analyzes buy link performance and conversion rates
* Suggests improvements to link configurations
* Recommends A/B testing for link optimization
* Alerts when poor link performance affects revenue

## Best Practices

### Regular Review Schedule

1. **Daily**: Check critical and high-priority actions
2. **Weekly**: Review all pending actions and trends
3. **Monthly**: Analyze action patterns and business impact
4. **Quarterly**: Evaluate overall optimization results

### Action Prioritization

1. **Address Critical Actions First**: Focus on actions that affect sales or customer experience
2. **Batch Similar Actions**: Apply related actions together for efficiency
3. **Test Before Bulk Changes**: Preview all changes, especially bulk operations
4. **Monitor Results**: Track the impact of applied actions

### Safety Guidelines

1. **Always Preview**: Review changes before applying any action
2. **Understand Impact**: Know how many records will be affected
3. **Confirm Bulk Operations**: Pay special attention to actions affecting 10+ records
4. **Backup Important Data**: Ensure you have backups before major changes
5. **Test in Development**: For complex changes, test in a development environment first

## Troubleshooting Common Issues

### Actions Not Appearing

* **Check Email**: Ensure you're receiving action notifications
* **Verify Dashboard**: Look for the action badge in your dashboard
* **Review Filters**: Make sure you're viewing all action categories
* **Contact Support**: If actions are missing, contact support

### Actions Won't Apply

* **Check Permissions**: Ensure you have proper access to modify data
* **Review Input Values**: Verify all required fields are completed correctly
* **Check Network**: Ensure stable internet connection during application
* **Retry Later**: Some actions may be temporarily unavailable

### Understanding Action Impact

* **Read Descriptions**: Carefully review action descriptions and recommendations
* **Check Preview**: Always preview changes before applying
* **Ask Questions**: Contact support if you're unsure about an action's impact
* **Start Small**: Begin with low-impact actions to understand the system

## Getting Help

### Support Resources

* **Email Support**: [support@elasticfunnels.io](mailto:support@elasticfunnels.io)
* **Documentation**: Browse related guides for more context
* **Preview Feature**: Use the preview function to understand changes
* **Action Descriptions**: Read detailed descriptions within each action

### When to Contact Support

* Actions seem incorrect or inappropriate
* Bulk operations affecting many records
* Unclear action descriptions or recommendations
* Technical issues preventing action application
* Questions about action impact on your business

<Warning>
  Always preview changes before applying actions, especially those affecting multiple records. The system provides safety warnings, but it's important to understand the impact of each action on your business.
</Warning>

## Related Documentation

* [Cost Optimization](/essentials/cost-optimization) - Understanding profit margins and pricing
* [Data Quality](/essentials/data-quality) - Maintaining accurate product information
* [SEO Best Practices](/essentials/seo) - Optimizing your pages for search engines
* [Buy Links](/products/buy-links) - Setting up and managing purchase links
* [Reconciliation](/integrations/reconciliation) - Syncing data with fulfillment providers


# Permission matrix
Source: https://docs.elasticfunnels.io/essentials/permission-matrix

A user-facing map of common ElasticFunnels capabilities to the permissions typically required.

## How to use this page

This matrix is designed for brand owners and organization admins who need to build or troubleshoot roles.

* Use the **capability** column to find the behavior you want.
* Use the **permission** column to configure the role.
* Also verify the related **module** is enabled for the brand.

## Core rules

* `*.view` usually controls whether a user can open a section or list.
* `*.create` controls creation flows.
* `*.update` controls edits, state changes, and many operational actions.
* `*.delete` controls destructive actions.
* `*.export` controls exports where supported.
* Metrics are separate from feature permissions.

## Common capability matrix

| Capability | Typical permission | Notes |
| - | - | - |
| Open Conversions list | `conversions.view` | Also requires the brand's conversions-related module to be enabled. |
| Create manual conversion-style flows | `conversions.create` | Plan rules may still limit creation in some cases. |
| Update conversion-related operational actions | `conversions.update` | Used for actions like subscription updates and fulfillment operational flows. |
| Open Customers report | `customers.view` | Separate from conversions visibility. |
| Export customers | `customers.export` | Export is separate from view. |
| Open Fulfillment list | `conversions.view` | Fulfillment list access is based on conversions access. |
| Configure or inspect integrations | `integrations.view` | Separate from fulfillment list visibility. |
| Open Merchants settings | `merchants.view` | Needed for merchant settings and some merchant-dependent selectors. |
| Open Products settings | `products.view` | Product management is separate from conversions/customers. |
| Open Pages | `pages.view` | Base pages access. |
| Open Advanced pages tools | `pagecomponents.view`, `collections.view`, `trackingscripts.view`, `backendscripts.view`, `files.view`, and related page permissions | Advanced page tooling can depend on several permissions. |
| Open Custom Reports | `reports.view` | In some UI contexts `analytics.view` may also appear; use the report-specific permission model when assigning roles. |
| Open Tracking reports | `tracking.view` or `reporting.utm_performance.view` | Depends on the report page. |
| Open Billing | `billing.invoices.view`, `billing.cards.view` | Billing checks use the `.view` form. |

## Metrics access matrix

Metrics are assigned separately from page permissions.

| Behavior | Metric requirement |
| - | - |
| See all dashboard metrics | `*` |
| See only selected metrics | Add only those metric keys to the role |
| Hide the dashboard metric grid, cards, and metrics table | Leave the role with no metric grants |

Examples of metric keys include:

* `revenue`
* `sales`
* `net_revenue`
* `conversion_rate`
* `refund_total`

## Recommended restricted-role patterns

### Conversions-only viewer

* `conversions.view`
* selected metrics if you want dashboard visibility

### Customers-only viewer

* `customers.view`
* `customers.export` only if export is required
* selected metrics only if you want dashboard analytics

### Reports reader

* `reports.view`
* report-specific permissions such as `conversions.view`, `customers.view`, `tracking.view`, or `reporting.utm_performance.view`
* selected metrics if the dashboard should also be visible

### Operations user

* `conversions.view`
* `conversions.update`
* optionally `integrations.view` if they should inspect integration setup
* optionally `merchants.view` if they need merchant settings or merchant-based selectors

## Important differences to remember

* **Feature permissions** decide what pages and actions a user can access.
* **Metrics** decide whether analytics widgets and dashboard numbers appear.
* A user may be able to view **Fulfillment** without being able to view **Integrations**.
* A user may see **Reports** but only be allowed into a subset of report pages.

## Next step

If a role still behaves unexpectedly, use [Restricted Role Troubleshooting](/essentials/restricted-role-troubleshooting).


# Restricted role troubleshooting
Source: https://docs.elasticfunnels.io/essentials/restricted-role-troubleshooting

How to configure restricted roles and diagnose why a user can or cannot see a page, menu item, or dashboard metric.

## Before you troubleshoot

When a restricted role does not behave as expected, check these in order:

1. Is the user in the correct organization and brand?
2. Is the related brand module enabled?
3. Does the role include the required permission?
4. Does the role include the required metrics for analytics widgets?

## Common symptoms

### “I cannot see a menu item”

Usually one of these is true:

* the brand module is disabled
* the role is missing the related `*.view` permission
* the parent section is filtered because none of its child pages are allowed

Examples:

* Missing `customers.view` means the Customers report item will not appear.
* Missing `conversions.view` means conversions-related reports and lists stay hidden.
* Missing both `billing.invoices.view` and `billing.cards.view` means Billing stays hidden.

### “I can see Reports, but it opens a different page than expected”

Reports opens the **first child page the user is allowed to access**.

That means:

* a user with `customers.view` but not `conversions.view` may land on Customers
* a user with only custom-report access may land on Custom Reports

This is expected behavior.

### “I can see the page, but the dashboard is empty”

Check the role's **metrics**, not just its permissions.

If the role has no metric grants, the user will not see:

* dashboard metric tiles
* dashboard cards
* the metrics table

This is expected for heavily restricted roles.

### “I can see Fulfillment, but not Integrations”

That can be correct.

* Fulfillment list access follows conversions/report access
* Integrations visibility is a separate permission area

A role can be allowed to work with fulfillment orders while still being blocked from integration setup pages.

### “I can see the menu, but the data will not load”

This usually means one of the following:

* the menu permission is present, but a deeper action permission is missing
* the user has the page permission, but not the required module
* the role was configured with feature permissions but no metric grants

## Example role setups

### Example 1: Conversions and customers viewer

Use this when someone should review orders and customers, but not manage settings.

Recommended permissions:

* `conversions.view`
* `customers.view`
* `customers.export` only if export is required

Recommended metrics:

* add only the dashboard metrics they should see
* leave metrics empty if they should not see dashboard analytics

Expected behavior:

* Reports is visible
* Reports opens the first allowed report child
* Conversions and Customers are available
* Settings areas such as merchants/products/integrations remain hidden unless added

### Example 2: Fulfillment operations user

Use this when someone should process fulfillment-related work.

Recommended permissions:

* `conversions.view`
* `conversions.update`

Optional additions:

* `integrations.view` if they should inspect integration setup
* `merchants.view` if they need merchant settings or merchant-related selectors

Expected behavior:

* Fulfillment list is visible
* operational actions are available if update permission is present
* Integrations may still be hidden unless explicitly granted

### Example 3: Dashboard-free support role

Use this when a teammate needs operational access but should not see analytics.

Recommended permissions:

* feature permissions needed for the role, such as `conversions.view` or `customers.view`

Recommended metrics:

* none

Expected behavior:

* the user can still access allowed lists and reports
* dashboard metrics, cards, and metrics table stay hidden

## Admin checklist

Before assigning a restricted role widely:

1. Test with a real non-owner account.
2. Open the sidebar and verify only intended sections appear.
3. Click Reports and confirm it opens the expected first child.
4. Open the dashboard and confirm metrics visibility matches the role's metric grants.
5. Test one read action and one operational action relevant to that role.

## Need the full mapping?

Use the [Permission Matrix](/essentials/permission-matrix) for a quick reference of common capabilities and their permission keys.


# Roles, permissions, and metrics
Source: https://docs.elasticfunnels.io/essentials/roles-permissions-metrics

How organization roles control menus, features, actions, and dashboard visibility in ElasticFunnels.

## Overview

ElasticFunnels uses **organization roles** to decide what each teammate can access. A role has:

* **Permissions**: dotted keys such as `conversions.view`, `pages.update`, `customers.export`.
* **Metrics**: which analytics numbers they may see on the dashboard, cards, and metrics table.

Owners always have full access. Users **not** in an organization (standalone brands) are not restricted by these lists.

## How access is decided

Most areas of the app check more than one thing:

1. The user must belong to the brand or organization.
2. The brand must have the related **module** enabled.
3. The user's role must include the required **permission**.
4. For analytics widgets, the user's role must also include the required **metrics**.

That means a user can sometimes:

* see a module in the brand setup, but not in the sidebar
* open a report section, but not every child page inside it
* have access to a feature, but still see no dashboard metrics

## What permissions affect

* **Sidebar and navigation**: Menu entries check both permissions and related modules.
* **Screens and actions**: Buttons, create flows, update actions, and exports can be restricted separately.
* **Reports**: The **Reports** section contains several child pages. You only see the report pages your role allows. Clicking **Reports** opens the **first report child you are allowed to access**.
* **Dashboard analytics**: Metrics, cards, and the metrics table are controlled by metric access, not only by feature permissions.

## Metrics vs permissions

Permissions control **features** (pages, conversions, settings, etc.). **Metrics** control **dashboard numbers** (sales, revenue, cards, breakdown tables).

If your role has **no metrics** assigned, the dashboard will **not** show:

* the main metrics grid
* metric cards
* the main metrics table

You may still be able to use reports, conversions, customers, pages, or settings if your feature permissions allow them.

## Common examples

### Reports behavior

If a user only has access to one report child, such as **Customers** or **Conversions**, the sidebar still shows **Reports**, and clicking it opens the first report page that user can actually access.

### Customers and conversions

* **Customers** — Viewing the Customers report requires `customers.view`. Export uses `customers.export`. Creating a manual customer order (which creates a purchase conversion) requires **`conversions.create`** in addition to appropriate customer access where applicable.
* **Fulfillment** — Viewing the fulfillment list is tied to **conversions** access. Seeing or configuring **integrations** is separate (`integrations.view`). You can have fulfillment orders listed even if you cannot open the Integrations screen.

### Billing

Billing visibility uses permissions such as `billing.invoices.view` and `billing.cards.view` (not the shorter `billing.invoices` labels).

## How to set up a restricted role

For a practical setup flow:

1. Start from an existing role that is close to the access level you want.
2. Remove feature permissions the user should not have.
3. Add only the metrics the user should be allowed to see.
4. Test with a real restricted user account before assigning the role broadly.

## Tips for admins

1. Start from a template role close to what you need, then remove permissions.
2. If someone sees a menu item but gets errors loading data, check both **permissions** and **module** toggles for the brand.
3. Set **metrics** explicitly for restricted roles; an empty metric list means **no** dashboard metrics.
4. Treat view, export, create, and update as separate capabilities. In some areas, being able to see a list does not mean the user can export or create.

## Next steps

* Use the [Permission Matrix](/essentials/permission-matrix) to map common capabilities to permission keys.
* Use [Restricted Role Troubleshooting](/essentials/restricted-role-troubleshooting) for setup examples and debugging steps.

For technical details of the enforcement stack, see the engineering note in the application repo: `docs/permission-inventory.md`.


# Export Collection Data
Source: https://docs.elasticfunnels.io/forms/export-data

Export your collected form data to CSV for analysis and external use

Exporting collection entries allows for data analysis or sharing outside the platform.

## How to Export Data

### Step 1: Access Collections

1. Go to "Collections" in your dashboard
2. Find the collection you need in the list
3. Click the "Export" button

### Step 2: Configure Export

A modal appears where you can:

* Enter your email address
* Choose "New entries only" if applicable
* Select the fields to export (e.g., Name, Email, Date Added)

### Step 3: Complete Export

1. Click "Export"
2. You'll receive an email once the export is complete

## Export Options

### Field Selection

* **All Fields**: Export complete records
* **Specific Fields**: Choose only the data you need
* **Custom Fields**: Include any custom attributes

### Date Filtering

* **All Time**: Export all collected data
* **Date Range**: Specify start and end dates
* **New Entries Only**: Export only data since last export

### Format Options

* **CSV Format**: Compatible with Excel and Google Sheets
* **UTF-8 Encoding**: Ensures special characters display correctly
* **Header Row**: Include field names as first row

## Data Analysis Tips

### Popular Use Cases

* **Email Marketing**: Import contacts into your email platform
* **CRM Integration**: Upload leads to your customer management system
* **Analytics**: Analyze trends and patterns in your data
* **Compliance**: Maintain records for legal requirements

### Best Practices

* Regular exports for backup purposes
* Clean data before importing to other systems
* Respect privacy laws (GDPR, CCPA) when handling exported data
* Secure storage of exported files

## Troubleshooting

### Common Issues

* **Large Exports**: May take longer to process - be patient
* **Email Delivery**: Check spam folder if export email doesn't arrive
* **File Corruption**: Re-export if CSV file won't open properly
* **Missing Data**: Verify field selections in export configuration

### Data Integrity

* Always verify exported data completeness
* Test import process with small sample first
* Keep original data as backup
* Document export procedures for consistency


# Lead Capture Forms
Source: https://docs.elasticfunnels.io/forms/lead-capture

Create and integrate lead capture forms to build your email list

Capture leads by creating a custom collection for storing user data, then embedding it into your page.

## Create a Collection Form

### Step 1: Set Up the Collection

1. Go to "Pages" → "Advanced" → "Collections"
2. Click "Create Collection"
3. Enter a name, define what happens on a new entry, and decide if you want to allow public export (e.g., for suppressions)

### Step 2: Configure Fields

1. Add fields (Text Field, Email Field, etc.)
2. Set attributes like required, searchable, private, and encrypt (for suppressions)

## Add Form to Your Page

### Step 3: Embed the Form

1. Go to the page builder and click the "+" button at the top left to add a new component
2. Search for your collection by name, then drag and drop the form

### Step 4: Configure Form Submission

1. Select the "Form" element in the "Layers" tab at the bottom left
2. In the properties tab, configure the success message or choose what to do after submission (show a modal, redirect, or display a message)
3. If opting to show a modal, create it first by adding a modal component

## Form Field Types

* **Text Field**: Single-line text input
* **Email Field**: Email validation included
* **Phone Field**: Phone number formatting
* **Textarea**: Multi-line text input
* **Dropdown**: Selection from predefined options
* **Checkbox**: Boolean yes/no options
* **Date Field**: Date picker functionality

## Advanced Features

* **Conditional Logic**: Show/hide fields based on user selections
* **Multi-step Forms**: Break long forms into multiple steps
* **Auto-fill**: Pre-populate fields with known user data
* **Validation Rules**: Custom validation for specific field requirements

## Optimization Tips

* Keep forms as short as possible
* Only ask for essential information initially
* Use clear, descriptive field labels
* Provide value before asking for information
* Test form submission thoroughly


# Thank You Pages
Source: https://docs.elasticfunnels.io/forms/thank-you-pages

Create custom thank you pages to confirm form submissions and guide next steps

A custom "thank you" page can confirm submission success and guide users to next steps.

<Note>
  This page covers thank-you pages for **form submissions** - lead magnets, contact forms, newsletter signups.

  For an **order confirmation** page that lists what the customer just bought, use
  [`getSessionOrders()`](/members-area/order-details) instead. It is scoped to the current
  checkout, so it shows the main product, any order bumps and every one-click upsell, complete on
  the first load. Do not use `getOrders()` there: it returns the customer's full purchase history
  and reads the search index, so a returning buyer can see previous orders and a just-accepted
  upsell can be missing until it is indexed.
</Note>

## Create and Stylize a "Thank You" Page

### Step 1: Create the Page

1. Create a new page named "Thank You"
2. Design and stylize it as you wish

### Step 2: Set Up the Collection Form

1. Create a collection and add it to the page where you collect data
2. Find the form in the layers list

### Step 3: Configure Redirection

1. In the form settings, choose "Redirect to URL" upon successful submission
2. Enter your "Thank You" page URL
3. Save

Submitting the form should now redirect users to the thank-you page.

## Thank You Page Best Practices

### Essential Elements

* **Clear confirmation message**: "Thank you for your submission!"
* **Next steps**: What the user should expect next
* **Contact information**: How to reach you if needed
* **Social media links**: Encourage following/sharing

### Advanced Features

* **Personalization**: Use submitted data to personalize the message
* **Additional offers**: Present related products or services
* **Download links**: Provide promised resources
* **Video messages**: Personal video thank you from team members

## Content Ideas

### For Lead Magnets

* Confirm the download link has been sent
* Set expectations for email frequency
* Provide immediate value with bonus content

### For Contact Forms

* Acknowledge receipt of their message
* Provide expected response timeframe
* Offer alternative contact methods

### For Newsletter Signups

* Welcome them to your community
* Share what type of content they'll receive
* Encourage them to whitelist your email address

## Technical Tips

* Ensure the thank you page loads quickly
* Make it mobile-friendly
* Consider adding tracking pixels for conversion measurement
* Test the redirect functionality thoroughly
* Set up proper analytics tracking for the thank you page


# Bindings & Events
Source: https://docs.elasticfunnels.io/frontend-template-engine/bindings-forms-events

ef-text/ef-html, ef-* attribute bindings, ef-value/data-template-value, @events, and Vue-style :bindings.

The frontend template engine supports **one-way** and **two-way** bindings and **event handlers**. All expressions are evaluated in the current scope (global + loop/block context).

## Text and HTML bindings

### `ef-text="expression"` (or `data-ef-text`)

Sets the element’s **`textContent`** from the expression (HTML is escaped). Updates automatically when scope changes.

```html theme={null}
<span ef-text="checkout.total"></span>
<p ef-text="item.name">Product Title</p>
```

Use for simple single-expression text. This is often easier to preview in the page builder than inline tokens.

Example equivalent:

```html theme={null}
<h2>[[ checkout.product_title ]]</h2>
<h2><span ef-text="checkout.product_title">Product Title</span></h2>
```

### `ef-html="expression"` (or `data-ef-html`)

Sets the element’s **`innerHTML`** from the expression. **Use only with trusted content** — no automatic escaping. Risk of XSS if the value comes from user input.

```html theme={null}
<div ef-html="checkout.product_description"></div>
```

Prefer **`data-ef-text`** or **`[[ ... ]]`** when the value is not fully trusted.

***

## One-way attribute bindings: `ef-href`, `ef-title`, `ef-alt`, `ef-placeholder`

Use these when you want scope-driven attributes without writing full `[[ ... ]]` strings in markup.

```html theme={null}
<a ef-href="links.checkout" ef-title="checkout.product_title">Continue</a>
<img ef-alt="checkout.product_title" ef-src="checkout.product_image" />
<input type="text" ef-placeholder="checkout.customer.email_placeholder" />
```

Supported aliases:

* `ef-href` / `data-ef-href`
* `ef-title` / `data-ef-title`
* `ef-alt` / `data-ef-alt`
* `ef-placeholder` / `data-ef-placeholder`

These are great for page builder workflows: add them in **Data Attributes** (right sidebar) when the component is selected.

***

## Two-way form binding: `ef-value` / `data-ef-value` / `data-template-value`

**`ef-value="path"`** (or `data-ef-value` / `data-template-value`) on **`input`**, **`select`**, or **`textarea`** binds the control to a **dot path** in scope (e.g. **`checkout.customer.email`**, **`billing.name`**).

* **Scope → element:** Engine sets value/checked from scope automatically on updates.
* **Element → scope:** On **`input`** or **`change`**, the engine writes the control’s value back to the path (creating nested objects as needed), then updates dependent UI.

### Supported controls

| Control | Path type | Behavior |
| - | - | - |
| **`input` text, email, tel, etc.** | String | `value` ↔ scope path |
| **`input type="checkbox"`** | Boolean | `checked` ↔ scope path |
| **`input type="radio"`** | Selected value (string) | One `ef-value`/`data-ef-value`/`data-template-value` on a radio (or each); path holds selected value; same `name` = one group. |
| **`textarea`** | String | `value` ↔ scope path |
| **`select`** | String (single) or array (multiple) | Single: path is string; multiple: path is array of selected option values |

### Example: checkout fields

```html theme={null}
<input type="email" id="email" name="email"
       ef-value="checkout.customer.email"
       required />

<select id="shipping_country" name="shipping_country"
        ef-value="checkout.customer.shipping_country" required>
  <option value="">Select Country</option>
  <template-foreach data-each="opt in checkout.countries">
    <option value="[[ opt.value ]]">[[ opt.label ]]</option>
  </template-foreach>
</select>

<label>
  <input type="checkbox" ef-value="checkout.shipping_same_as_billing" />
  Shipping same as billing
</label>
```

When the user toggles the checkbox, **`checkout.shipping_same_as_billing`** updates and dependent blocks (like `<template-if data-condition="!checkout.shipping_same_as_billing">`) react automatically.

### `data-set-onload`

When present, **if the scope path is undefined on the first run**, the element’s current value/checked is **written to scope**. Useful so HTML defaults (e.g. **`checked`** on a checkbox) drive template logic on load.

```html theme={null}
<input type="checkbox" ef-value="billing.agree" data-set-onload checked />
```

***

## One-way bindings: `:checked`, `:disabled`, `:value`

Vue-style **one-way** bindings: the expression is evaluated and the **DOM property** is set on each update. The attribute is removed after first apply and the expression is stored in memory so the DOM stays clean.

* **`:checked="expression"`** — Sets **`element.checked`** (e.g. **`:checked="bumpSelected"`**).
* **`:disabled="expression"`** — Sets **`element.disabled`**.
* **`:value="expression"`** — Sets **`element.value`**.

Use when the value is **derived from scope** and the user does not edit it back (e.g. a disabled state, or a display-only value). For user-editable form fields, use **`ef-value`** (or aliases) for two-way binding.

```html theme={null}
<button :disabled="submitting">Submit</button>
<input type="checkbox" :checked="bumpSelected" />
```

***

## Event handlers: `@click` and others

**`@click="expression"`** runs the expression when the element (or a child) is clicked. The expression is evaluated in a context that includes **`$event`** / **`event`** (the DOM event) and **`$el`** / **`$target`** (element). Assignments in the expression (e.g. **`items = []`**, **`item.open = !item.open`**) mutate scope and the UI re-renders automatically.

### Aliases

* **`@click`** — Short form.
* **`data-ef-on:click`**, **`data-ef-on-click`**, **`data-ef-click`** — Attribute forms.

Same pattern for other events: **`@submit`**, **`@change`**, **`@input`**, **`@blur`**, **`@focus`**, etc. The engine discovers used event names from the DOM and binds them once.

### Examples

```html theme={null}
<button @click="items.push({ code: 'X', name: 'New', price: 9.99, quantity: 1 })">
  Add item
</button>

<button @click="items = []">Clear cart</button>

<button @click="faq.open = !faq.open">
  [[ faq.open ? 'Hide' : 'Show' ]]
</button>
```

Returning **`false`** from the expression calls **`preventDefault()`** on the event.

### Cart and bumps

For **cart quantity** and **remove**, prefer the cart plugin’s **data attributes** so behavior is consistent without custom script:

* **Decrease qty:** **`data-cart-qty-minus`** and **`data-code="[[ item.code ]]"`** (so the plugin gets the actual code); optional **`data-disable-when-one`** to disable when `item.quantity <= 1`.
* **Increase qty:** **`data-cart-qty-plus`** and **`data-code="[[ item.code ]]"`**.
* **Remove:** **`data-cart-qty-remove`** and **`data-code="[[ item.code ]]"`**.

When you need **custom @click** logic, you can use **`window.ef.addToCart(code, options?, quantity?)`**, **`ef.setCartQuantity(code, quantity)`**, **`ef.removeFromCart(code, allowClear?)`** if the app exposes **`window.ef`**.

***

## Lifecycle & visibility directives

Element-level handlers that run when an element enters the DOM, leaves the DOM, or scrolls into the viewport. They share the same expression model and alias families as **`@click`** — the expression runs in the current scope and can read **`$el`** (the element itself).

### `@mounted="expression"`

Runs **once** after the element is inserted into the live DOM. Useful for initializing third-party widgets, setting focus, or kicking off animations on elements rendered by **`template-if`** or **`template-foreach`**.

```html theme={null}
<div @mounted="initSlider($el)">…</div>

<template-foreach data-each="card in cards">
  <article @mounted="trackImpression(card.id)">[[ card.title ]]</article>
</template-foreach>
```

Notes:

* Fires **once per element instance**. Re-renders of the same element do not re-fire it.
* Hiding a **`template-if`** branch and showing it again creates a new element instance, so **`@mounted`** runs again.
* Deferred to the next animation frame so layout has settled before the handler runs.

### `@unmounted="expression"`

Runs just **before** the element is removed from the DOM (e.g. when a **`template-if`** condition flips false or a **`template-foreach`** item drops out).

```html theme={null}
<div @mounted="player = createPlayer($el)" @unmounted="player.destroy()">
  …
</div>
```

Use it to dispose timers, observers, or third-party instances created in **`@mounted`**.

### `@visible="expression"`

Runs when the element scrolls into the viewport, backed by an **`IntersectionObserver`** under the hood.

```html theme={null}
<section @visible="seen = true">…</section>

<div @visible.every="trackImpression($el)">…</div>
```

Modifiers:

* **`@visible.once`** *(default)* — Fires only the first time the element enters the viewport, then disconnects.
* **`@visible.every`** — Fires every time the element re-enters the viewport.

Optional fine-tuning attributes (apply to the same element):

* **`data-ef-visible-threshold="0..1"`** — Fraction of the element that must be visible to fire (default **`0`**: any pixel).
* **`data-ef-visible-margin="100px 0px"`** — **`rootMargin`** passed to the observer; positive values fire earlier (before the element actually scrolls into view).

```html theme={null}
<div @visible="impressionTracked = true"
     data-ef-visible-threshold="0.5"
     data-ef-visible-margin="0px 0px -100px 0px">
  Fires when 50% visible, with the bottom 100px shaved off the viewport.
</div>
```

The expression receives **`$event`** as the **`IntersectionObserverEntry`** when fired.

### Aliases

All three directives accept the same alias families as **`@click`**:

| Short | `data-ef-on:` | `data-ef-on-` | `data-ef-` |
| - | - | - | - |
| **`@mounted`** | **`data-ef-on:mounted`** | **`data-ef-on-mounted`** | **`data-ef-mounted`** |
| **`@unmounted`** | **`data-ef-on:unmounted`** | **`data-ef-on-unmounted`** | **`data-ef-unmounted`** |
| **`@visible`** | **`data-ef-on:visible`** | **`data-ef-on-visible`** | **`data-ef-visible`** |

Modifier forms also accept dash variants for environments where dots in attribute names are awkward — e.g. **`data-ef-on:visible.once`**, **`data-ef-on-visible-once`**, **`data-ef-visible-every`**.

### When to prefer the JS API

For watchers tied to **scope paths** rather than DOM elements, use **`window.ef.template.watch(path, fn, { immediate, deep })`** — see [Scope & Data](/frontend-template-engine/scope-and-data#runtime-api-watch-and-computed). Use the markup directives when the trigger is **DOM lifecycle or viewport visibility** of a specific element.

***

## Reactivity summary

* **`[[ expression ]]`** — Re-evaluated automatically after relevant scope changes.
* **Mounted `template-if` and `template-foreach`** — Re-render automatically when dependencies change.
* **`ef-value` / aliases** — Scope → element on updates; element → scope on **input** / **change**.
* **`ef-text` / `ef-html` / `ef-src` / `ef-href` / `ef-title` / `ef-alt` / `ef-placeholder` / `:checked` / `:disabled` / `:value`** — Applied on reactive updates.
* **`@mounted` / `@unmounted` / `@visible`** — Run when the element is inserted into / removed from the DOM, or first scrolls into the viewport.

Next: [Functions](/frontend-template-engine/built-in-functions).


# Functions
Source: https://docs.elasticfunnels.io/frontend-template-engine/built-in-functions

formatPrice, cartCount, cartSubtotal, lineTotal, and string helpers. When to use formatPrice vs pre-formatted values.

Expressions in **`[[ ... ]]`**, **`data-condition`**, **`data-ef-text`**, and similar attributes can call **built-in functions**. You can also **register** custom functions with **`registerTemplateFunction(name, fn)`** or **`registerTemplateFunctions({ name: fn, ... })`**.

***

## Price display: when to use `formatPrice` vs as-is

Most **checkout** and **cart** values are **already formatted** (e.g. `"$29.00"`). Use them directly in **`[[ ... ]]`**. Use **`formatPrice()`** only when you need to display a **raw number** (e.g. **`*_raw`** keys or a computed number).

<Tabs>
  <Tab title="Use as-is (no formatPrice)">
    These are **pre-formatted**. Use **`[[ variable ]]`** only.

    | Variable | Example |
    | - | - |
    | **Checkout totals** | `checkout.product_price`, `checkout.retail_price`, `checkout.bump_total`, `checkout.subtotal_before_discount`, `checkout.discount_total`, `checkout.subtotal_after_discount`, `checkout.subtotal` (alias), `checkout.shipping`, `checkout.tax`, `checkout.total` |
    | **Cart item** | `item.price`, `item.total`, `item.retail_price`, `item.discount_total` |
    | **Bump / line** | `bump.price`, `line.price` |

    **In template:** `[[ checkout.total ]]`, `[[ item.price ]]`, `[[ bump.price ]]`
  </Tab>

  <Tab title="Use formatPrice (raw numbers)">
    Use **`formatPrice(value, currency?)`** when displaying a **numeric** value that has no formatted key, or when you explicitly use a **`_raw`** key.

    | When | Example |
    | - | - |
    | **Checkout \_raw keys** | `formatPrice(checkout.total_raw, checkout.currency)` — only if you must show a raw number; normally use formatted keys (`checkout.total`, etc.). Raw keys include `product_price_raw`, `retail_price_raw`, `bump_total_raw`, `subtotal_before_discount_raw`, `discount_total_raw`, `subtotal_after_discount_raw`, `subtotal_raw` (alias), `shipping_raw`, `tax_raw`, `total_raw`. |
    | **Bump/line raw** | `formatPrice(bump.price_raw, checkout.currency)` — for display of raw; normal display use `[[ bump.price ]]`. |
    | **Computed value** | `formatPrice(lineTotal(item), currency)` — when `item.total` is not provided. |
  </Tab>
</Tabs>

<Warning>
  Do **not** pass an already-formatted string into **formatPrice** (e.g. `formatPrice(checkout.total, ...)` or `formatPrice(item.price, ...)`). That can produce wrong or duplicated currency symbols.
</Warning>

***

## `formatPrice(value, currency?, locale?)` / `money` / `formatCurrency`

Formats a **numeric** value as currency.

| Parameter | Description |
| - | - |
| **value** | Number (or parseable to number) |
| **currency** | Optional. Code (e.g. `USD`) or symbol. If omitted, uses `checkout.currency` or `scope.currency` or `USD`. |
| **locale** | Optional. For `Intl.NumberFormat`. |

***

## Cart helpers

| Function | Returns | Example |
| - | - | - |
| **`lineTotal(item, quantityKey?, priceKey?)`** | quantity × price for one item (default keys: `quantity`, `price`) | `[[ formatPrice(lineTotal(item), currency) ]]` when `item.total` is not in scope |
| **`cartCount(items)`** / **`cart_count(items)`** | Sum of item quantities | `[[ cartCount(cartItems) ]]` |
| **`cartSubtotal(items, quantityKey?, priceKey?)`** / **`cart_subtotal(...)`** | Numeric sum of line totals | `[[ formatPrice(cartSubtotal(cartItems), checkout.currency) ]]` |

***

## String helpers

All coerce to string; `null`/`undefined` become empty string.

| Function | Description | Example result |
| - | - | - |
| **`upper`** / **`uppercase`** | Uppercase | "ALPHA" |
| **`lower`** / **`lowercase`** | Lowercase | "alpha" |
| **`capitalize`** | First character uppercase | "Alpha" |
| **`titleCase`** / **`title`** | Title case | "Product Alpha" |
| **`camelCase`** / **`camel`** | camelCase | "someLabel" |
| **`snakeCase`** / **`snake`** | snake\_case | "some\_label" |
| **`kebabCase`** / **`kebab`** | kebab-case | "some-label" |

***

## Custom functions

Register from application or plugin code:

```javascript theme={null}
import { registerTemplateFunction, registerTemplateFunctions } from './utils/templateProcessor.js';

registerTemplateFunction('myFormat', (value) => {
  return value != null ? String(value).toUpperCase() : '';
});

registerTemplateFunctions({
  double: (n) => Number(n) * 2,
  greet: (name) => `Hello, ${name || 'Guest'}!`
});
```

Then in templates: **`[[ myFormat(item.name) ]]`**, **`[[ double(item.quantity) ]]`**, **`[[ greet(checkout.customer.first_name) ]]`**.

***

## Summary

* **Price display:** Use the [table above](#price-display-when-to-use-formatprice-vs-as-is): pre-formatted keys as-is; **formatPrice** only for **raw** values or computed numbers.
* **Cart:** **`cartCount`**, **`cartSubtotal`**, **`lineTotal`**; combine with **formatPrice** when you need a formatted string from a number.
* **Strings:** **`upper`**, **`lower`**, **`capitalize`**, **`titleCase`**, **`camelCase`**, **`snakeCase`**, **`kebabCase`** (and aliases).
* **Custom:** **`registerTemplateFunction`** / **`registerTemplateFunctions`**.

Next: [Cart](/frontend-template-engine/cart) and [Checkout](/frontend-template-engine/checkout).


# Cart
Source: https://docs.elasticfunnels.io/frontend-template-engine/cart

Cart items, quantity controls, and data attributes for the template engine and cart plugin.

This page covers **cart** usage: **`cartItems`**, item properties, and **data attributes** for quantity and remove. For checkout-only topics (totals, form fields, coupon, payment), see [Checkout](/frontend-template-engine/checkout).

***

## Scope: `cartItems` / `items`

**`cartItems`** (or **`items`**) is an array of line items. The cart plugin fills it; UI updates are reactive when cart scope changes.

| Item property | Type | Description | In template |
| - | - | - | - |
| **`code`** | string | Product/cart line code | Use with qty/remove data attributes |
| **`name`** | string | Product name | `[[ item.name ]]` |
| **`image`** | string | Product image URL | `[[ item.image ]]` |
| **`quantity`** | number | Quantity | `[[ item.quantity ]]` |
| **`price`** | string | Unit price (formatted) | `[[ item.price ]]` — do not use formatPrice |
| **`total`** | string | Line total (formatted) | `[[ item.total ]]` — do not use formatPrice |
| **`retail_price`** | string | Original/retail price (formatted) | `[[ item.retail_price ]]` |
| **`discount_total`** | string | Per-line savings (formatted) | `[[ item.discount_total ]]` |
| **`currency`** | string | Currency code | `[[ item.currency ]]` |
| **`is_subscription`** | boolean | `true` when this is a subscription product | `[[ item.is_subscription ]]` |
| **`subscription`** | object \| null | Subscription details (see below) — `null` for one-time products | `[[ item.subscription.frequency ]]` |
| **`bonuses`** | array | Bonus products included with this item (see below) | `template-foreach` loop |
| **`courses`** | array | Courses linked to this product (see below) | `template-foreach` loop |

<Info>
  **`price`** and **`total`** are already formatted. Use **`[[ item.price ]]`** and **`[[ item.total ]]`** as-is. See [Functions](/frontend-template-engine/built-in-functions#price-display-table) for when to use **formatPrice**.

  `bonuses`, `courses`, `is_subscription`, and `subscription` are populated after a brief async fetch from the server when the cart loads. They are always present (empty array / `false` / `null`) so templates never error.
</Info>

***

## Subscription details (`item.subscription`)

When `item.is_subscription` is `true`, `item.subscription` contains billing cadence and trial settings:

| Property | Type | Description |
| - | - | - |
| **`frequency`** | number | How often the subscription bills (e.g. `3`) |
| **`frequency_unit`** | string | Unit for the frequency: `"day"`, `"week"`, `"month"`, or `"year"` |
| **`trial_days`** | number | Free trial length in days (`0` = no trial) |
| **`first_charge_free`** | boolean | `true` when the first billing cycle is free |

Example — showing billing cadence next to the price:

```html theme={null}
<template-foreach data-each="item in cartItems">
  <span>[[ item.name ]]</span>
  <span>[[ item.price ]]</span>
  <template-if data-condition="item.is_subscription">
    <span>Every [[ item.subscription.frequency ]] [[ item.subscription.frequency_unit ]]</span>
  </template-if>
</template-foreach>
```

The same `is_subscription` and `subscription` fields are available on `checkout` scope for single-product checkout pages (e.g. `[[ checkout.is_subscription ]]`, `[[ checkout.subscription.frequency ]]`).

***

## Bonus products (`item.bonuses`)

Each cart item may include a **`bonuses`** array — products that are included free with that item (configured in the product catalog under Bonuses). Populated automatically from the `/api/cart-products` response after the cart loads.

Each element in `item.bonuses` has:

| Property | Description |
| - | - |
| **`code`** | Bonus product code |
| **`name`** | Bonus product name |
| **`image`** | Bonus product image URL |
| **`price`** | Price (formatted) — typically `$0.00` for free bonuses |
| **`retail_price`** | Retail value (formatted) — useful for "valued at" display |
| **`original_price`** | Same as `retail_price` |
| **`currency`** | Currency code |

Example:

```html theme={null}
<template-foreach data-each="item in cartItems">
  <div class="cart-line">
    <img src="[[ item.image ]]" alt="[[ item.name ]]" />
    <span>[[ item.name ]]</span>
    <span>[[ item.price ]]</span>
    <template-foreach data-each="bonus in item.bonuses">
      <div class="cart-bonus">
        <img src="[[ bonus.image ]]" alt="[[ bonus.name ]]" />
        <span>[[ bonus.name ]]</span>
        <span>FREE (valued at [[ bonus.retail_price ]])</span>
      </div>
    </template-foreach>
  </div>
</template-foreach>
```

`item.bonuses` is always an array — empty when the product has no bonuses configured.

***

## Courses (`item.courses`)

When a product has linked courses, they are available as `item.courses`. Populated automatically from the `/api/cart-products` response after the cart loads.

Each element in `item.courses` has:

| Property | Description |
| - | - |
| **`id`** | Course ID |
| **`title`** | Course title |
| **`slug`** | URL slug (used to link to the course page) |
| **`description`** | Short description |
| **`cover`** | Cover image URL |
| **`instructor_name`** | Instructor name (if set) |
| **`status`** | Publication status (`"published"`, `"draft"`, etc.) |

Example — listing included courses beneath a cart line:

```html theme={null}
<template-foreach data-each="item in cartItems">
  <span>[[ item.name ]]</span>
  <template-foreach data-each="course in item.courses">
    <div class="cart-course">
      <img src="[[ course.cover ]]" alt="[[ course.title ]]" />
      <span>[[ course.title ]]</span>
    </div>
  </template-foreach>
</template-foreach>
```

`item.courses` is always an array — empty when the product has no linked courses.

***

## Quantity and remove (data attributes)

Use these so the **cart plugin** handles +/- and remove without custom script:

| Attribute | Element | Purpose |
| - | - | - |
| **`data-cart-qty-minus`** | Button | Decrease quantity |
| **`data-cart-qty-plus`** | Button | Increase quantity |
| **`data-cart-qty-remove`** | Button/link | Remove line (set qty to 0) |
| **`data-code="[[ item.code ]]"`** | Same element or parent | So the plugin receives the actual product code |
| **`data-disable-when-one`** | Minus button (optional) | Disable when `item.quantity <= 1` |

Example:

```html theme={null}
<template-foreach data-each="item in cartItems">
  <div class="cart-line">
    <img alt="[[ item.name ]]" src="[[ item.image ]]" />
    <span>[[ item.name ]]</span>
    <button type="button" data-cart-qty-minus data-code="[[ item.code ]]" data-disable-when-one aria-label="Decrease">−</button>
    <span>[[ item.quantity ]]</span>
    <button type="button" data-cart-qty-plus data-code="[[ item.code ]]" aria-label="Increase">+</button>
    <span>[[ item.total ]]</span>
    <button type="button" data-cart-qty-remove data-code="[[ item.code ]]" aria-label="Remove">Remove</button>
  </div>
</template-foreach>
```

You can wrap the Remove button in **`<template-if data-condition="cartItems.length > 1">`** so it only shows when there is more than one item (use **`&gt;`** for `>` in **`data-condition`**).

For custom behavior, use **`@click`** with **`window.ef.addToCart(code, options?, quantity?)`**, **`window.ef.setCartQuantity(code, quantity)`**, or **`window.ef.removeFromCart(code, allowClear?)`** if the app exposes **`window.ef`**.

***

## Order bumps (on checkout)

On checkout pages, bump cards use these **data attributes** so the bump-products plugin can toggle and style:

| Attribute | Where | Purpose |
| - | - | - |
| **`data-bump-code="[[ bump.code ]]"`** | Card/container | Plugin adds `.selected` / `.bump-selected` when selected |
| **`data-bump-checkbox="[[ bump.code ]]"`** | Checkbox | Links checkbox to bump code |
| **`data-bump-toggle="[[ bump.code ]]"`** | Label or clickable wrapper | Click toggles the checkbox |
| **`name="bump"`** or **`name="bump[]"`**, **`value="[[ bump.code ]]"`** | Checkbox | Form submit and plugin read selected codes |

For **scope** (**`checkout.bump_products`**, **`checkout.selectedBumpLines`**) and full **offer vs added** template pattern, see [Checkout — Order bumps](/frontend-template-engine/checkout#order-bumps).

***

## Summary

* Use **`cartItems`** and **`[[ item.* ]]`**; **`item.price`** and **`item.total`** are already formatted.
* **`item.is_subscription`** / **`item.subscription`** — billing cadence; also on `checkout` scope for single-product pages.
* **`item.bonuses`** — free bonus products linked to the item; always an array.
* **`item.courses`** — courses linked to the product; always an array.
* Use **data-cart-qty-minus/plus/remove** and **data-code** for qty and remove.
* Bumps: use **data-bump-**\* attributes; scope and patterns are in [Checkout](/frontend-template-engine/checkout).


# Checkout
Source: https://docs.elasticfunnels.io/frontend-template-engine/checkout

Checkout-specific template engine usage: totals, form fields, coupon, order bumps, payment panel, and validation.

This page covers **checkout-only** usage of the frontend template engine: order summary, totals, form fields, coupon, order bumps, and payment. For cart items and quantity controls, see [Cart](/frontend-template-engine/cart).

<Info>
  **`checkout`** exists only on checkout pages. Guard shared templates with `<template-if data-condition="checkout">` when using `checkout.*`.
</Info>

***

## Order summary: single-product vs cart

Checkout can show either a **single-product** block (one product, hero image + title) or a **cart** block (list of items with thumbnails and qty). Use the scope flags to choose.

| Condition | When it's true | Use in template |
| - | - | - |
| **`is_single_product`** | One product in cart | `checkout.product_image`, `checkout.product_title`, `checkout.product_price`, `checkout.retail_price` |
| **`is_cart`** | Multiple items | `<template-foreach data-each="item in cartItems">` with `[[ item.image ]]`, `[[ item.name ]]`, `[[ item.total ]]` |

<Warning>
  Do **not** use `cartItems[0]` in the single-product block. Use **`checkout.product_*`** keys only.
</Warning>

```html theme={null}
<template-if data-condition="is_single_product">
  <div class="order-summary-single">
    <img src="[[ checkout.product_image ]]" alt="[[ checkout.product_title ]]" />
    <h2>[[ checkout.product_title ]]</h2>
    <span>[[ checkout.product_price ]]</span>
    <span>[[ checkout.retail_price ]]</span>
  </div>
</template-if>
<template-else-if data-condition="is_cart">
  <template-foreach data-each="item in cartItems">
    <div class="order-summary-line">
      <img src="[[ item.image ]]" alt="[[ item.name ]]" />
      <span>[[ item.name ]]</span>
      <span>[[ item.total ]]</span>
    </div>
  </template-foreach>
</template-else-if>
```

Equivalent binding-style variant (often easier to preview/edit in the page builder):

```html theme={null}
<template-if data-condition="is_single_product">
  <div class="order-summary-single">
    <img ef-src="checkout.product_image" ef-alt="checkout.product_title" />
    <h2><span ef-text="checkout.product_title">Product Title</span></h2>
    <span ef-text="checkout.product_price">$0.00</span>
    <span ef-text="checkout.retail_price">$0.00</span>
  </div>
</template-if>
```

You can add `ef-*` attributes from the **Data Attributes** section (right sidebar) when a component is selected.

***

## Subscription products

On single-product checkout pages, `checkout.is_subscription` and `checkout.subscription` are set **server-side** and available immediately when the page loads — no async fetch required.

| Key | Type | Description |
| - | - | - |
| **`checkout.is_subscription`** | boolean | `true` when the product is a subscription |
| **`checkout.subscription`** | object \| null | Billing cadence details — `null` for one-time products |
| **`checkout.subscription.frequency`** | number | How often the subscription bills (e.g. `3`) |
| **`checkout.subscription.frequency_unit`** | string | `"day"`, `"week"`, `"month"`, or `"year"` |
| **`checkout.subscription.trial_days`** | number | Free trial length in days (`0` = no trial) |
| **`checkout.subscription.first_charge_free`** | boolean | `true` when the first cycle is free |
| **`checkout.subscription.intro_offer`** | object \| null | `null` unless an intro offer is enabled on the product |
| **`checkout.subscription.intro_offer.price`** | number \| null | Intro price |
| **`checkout.subscription.intro_offer.period`** | number \| null | Intro period length (e.g. `2`) |
| **`checkout.subscription.intro_offer.period_unit`** | string \| null | `"day"`, `"week"`, `"month"`, or `"year"` |
| **`checkout.subscription.intro_offer.recurring_price`** | number \| null | Price charged after the intro period ends |
| **`checkout.subscription.price_steps`** | array \| null | Stepped pricing schedule; `null` when not configured |
| **`checkout.subscription.prepaid.discount_3_month`** | number \| null | Prepaid 3-month discount |
| **`checkout.subscription.prepaid.discount_6_month`** | number \| null | Prepaid 6-month discount |
| **`checkout.subscription.prepaid.discount_12_month`** | number \| null | Prepaid 12-month discount |
| **`checkout.subscription.tiers`** | array \| null | Subscription tiers; `null` when not configured |

Intro-offer copy, for example:

```html theme={null}
<template-if data-condition="checkout.subscription.intro_offer">
  <p>
    [[ formatPrice(checkout.subscription.intro_offer.price) ]] for your first
    [[ checkout.subscription.intro_offer.period ]] [[ checkout.subscription.intro_offer.period_unit ]],
    then [[ formatPrice(checkout.subscription.intro_offer.recurring_price) ]].
  </p>
</template-if>
```

Use `template-if` to show subscription-specific UI only when the product is a subscription:

```html theme={null}
<template-if data-condition="checkout.is_subscription">
  <p class="billing-notice">
    You'll be billed every [[ checkout.subscription.frequency ]] [[ checkout.subscription.frequency_unit ]].
  </p>
</template-if>

<template-if data-condition="checkout.is_subscription && checkout.subscription.trial_days > 0">
  <p class="trial-notice">
    Your [[ checkout.subscription.trial_days ]]-day free trial starts today.
  </p>
</template-if>

<template-if data-condition="checkout.is_subscription && checkout.subscription.first_charge_free">
  <p class="trial-notice">First [[ checkout.subscription.frequency_unit ]] is free.</p>
</template-if>
```

For **cart-mode checkout** (multiple items), subscription info is on each cart item instead: `item.is_subscription` and `item.subscription`. See [Cart — Subscription details](/frontend-template-engine/cart#subscription-details-itemsubscription).

***

## Totals (display + raw)

Checkout exposes the same totals keys in **both** modes (`is_single_product` and `is_cart`) so one layout can be reused for either flow.

Use formatted keys for display (`[[ checkout.total ]]`). Use `*_raw` only for conditions/math.

| Formatted key | Raw key | Meaning |
| - | - | - |
| **`checkout.product_price`** | **`checkout.product_price_raw`** | Main products amount (excludes bumps). |
| **`checkout.retail_price`** | **`checkout.retail_price_raw`** | Retail/original amount for main products. |
| **`checkout.bump_total`** | **`checkout.bump_total_raw`** | Selected order bumps total. |
| **`checkout.subtotal_before_discount`** | **`checkout.subtotal_before_discount_raw`** | Product + bumps before coupon discount. |
| **`checkout.discount_total`** | **`checkout.discount_total_raw`** | Coupon discount amount. |
| **`checkout.subtotal_after_discount`** | **`checkout.subtotal_after_discount_raw`** | Subtotal after coupon discount, before shipping/tax. |
| **`checkout.subtotal`** | **`checkout.subtotal_raw`** | Backward-compatible alias of `subtotal_after_discount`. |
| **`checkout.shipping`** | **`checkout.shipping_raw`** | Shipping amount. |
| **`checkout.tax`** | **`checkout.tax_raw`** | Tax amount. |
| **`checkout.total`** | **`checkout.total_raw`** | Final grand total. |

Recommended template bindings:

* Subtotal row: `[[ checkout.subtotal_after_discount ]]`
* Total row: `[[ checkout.total ]]`
* Conditions: `checkout.bump_total_raw > 0`, `checkout.tax_raw > 0`, `checkout.shipping_raw > 0`

***

## Form fields and validation

### Binding fields

Use **`data-template-value="checkout.customer.<field>"`** on each input/select. Paths follow the checkout field spec (e.g. `checkout.customer.email`, `checkout.customer.shipping_first_name`).

* Wrap each field in a container (e.g. **`.floating-label-group`**).
* Add **`<div class="form-error" data-checkout-error="<id>"></div>`** so the form errors adapter can show validation messages.
* Use **`checkout.countries`** and **`checkout.usStates`** for select options (each **`{ value, label }`**).

### Enforce country/state restrictions server-side

Use backend code to enforce checkout country/state restrictions on submit. Set `checkout_settings` in `<script scope="backend">` with `setVariable(...)`:

```html theme={null}
<script scope="backend">
setVariable('checkout_settings', {
  countries: ['US'],
  usStates: ['CA', 'TX', 'FL']
});
</script>
```

This does two things:

* Restricts the rendered `checkout.countries` / `checkout.usStates` lists.
* Enforces the same allowlist in `process-checkout` (invalid country/state returns validation errors).

Use code values in options:

```html theme={null}
<select name="shipping_country" data-template-value="checkout.customer.shipping_country">
  <option value="">Select Country</option>
  <template-foreach data-each="opt in checkout.countries">
    <option value="[[ opt.value ]]">[[ opt.label ]]</option>
  </template-foreach>
</select>
```

### Shipping same as billing

* Bind the checkbox with **`data-template-value="checkout.shipping_same_as_billing"`**.
* Wrap the **shipping address block** in **`<template-if data-condition="!checkout.shipping_same_as_billing">`**.
* Use **`<template-else>`** to show a short message when shipping equals billing.

### Billing section visibility

The **entire billing info section** can be wrapped in **`<template-if data-condition="checkout.shipping_same_as_billing == false">`** so the billing block is hidden when “same as billing” is checked. Inside that section, use **`<template-if data-condition="!checkout.shipping_same_as_billing">`** for the visible billing form and **`<template-else>`** for a short message plus hidden billing inputs so the backend still receives billing data.

### Validation errors

* **`errors`** is an object keyed by field id: **`errors['email']`**, **`errors['shipping_city']`**, etc.
* The form errors adapter looks for **`[data-checkout-error="<id>"]`** and sets the message; it also adds **`.error`** to the input and **`.has-error`** to the wrapper.
* You can show the message in the template: **`[[ errors[f.id] ]]`** or **`data-ef-text="errors['email']"`**.

***

## Coupon

| Scope | Purpose |
| - | - |
| **`query.coupon`** | URL has `?coupon=...` — use for *showing* the “automatically applied” block. |
| **`checkout.coupon`** | Applied coupon: **`applied`**, **`code`**, **`name`**, **`value_formatted`**. |
| **`checkout.coupon_message`** | Validation error message (e.g. invalid code). |

* **Apply button:** **`data-apply-coupon`** (plugin binds to validate + refresh).
* **Clear button:** **`data-clear-coupon`**; show when **`checkout.coupon.applied`**.
* **Error block:** **`<template-if data-condition="checkout.coupon_message">`** with **`[[ checkout.coupon_message ]]`**.

***

## Order bumps

| Scope | Purpose |
| - | - |
| **`checkout.bump_products`** | All available bumps (each: **`code`**, **`name`**, **`description`**, **`price`** formatted, **`price_raw`**, **`image`**, **`added`**). |
| **`checkout.selectedBumpLines`** | Selected bumps (each: **`code`**, **`name`**, **`price`**, **`price_raw`**). |

* Display **`[[ bump.price ]]`** and **`[[ line.price ]]`** as-is (already formatted).
* **Checkbox pattern:** Use **`data-bump-code`**, **`data-bump-checkbox`**, **`data-bump-toggle`** and **`name="bump"`**, **`value="[[ bump.code ]]"`** so the bump plugin can toggle and style. See [Cart](/frontend-template-engine/cart#order-bumps) for the full offer vs added pattern.
* **Button + @click pattern:** Alternatively, use **`<button @click="bump.added = true">…</button>`** for “Add to order” and **`<button @click="bump.added = false">…</button>`** for “Remove”. Mutating **`bump.added`** triggers re-render. Both checkbox + **data-bump-**\* and button + **@click** are valid.

***

## Payment panel

**Pattern A (generic):** Replace the payment block with **only**:

```html theme={null}
<checkout-cc-panel></checkout-cc-panel>
```

The app injects the full payment UI (method choice, card inputs, etc.). Do not keep duplicate payment method pickers or card sections in the template.

**Pattern B (explicit gateway):** When the source already has an explicit gateway structure (e.g. NMI), preserve it. Use a wrapper **`<div class="checkout-cc-panel" data-gateway="nmi">`** (or other gateway). Inside: (1) optional cardholder name in **`<template-if data-condition="!(checkout && checkout.customer && checkout.customer.first_name)">`** with **`data-template-value="checkout.customer.cardholder_name"`** and **`<div class="form-error" id="cc-name-error"></div>`**; (2) a **secure-card-element** div with **`data-brand-id`**, **`data-domain-id`**, **`data-merchant-code`**, **`data-accepted-cards`**, plus a sibling **`<div class="form-error" id="nmi-card-errors"></div>`** for card errors.

### Smart field detection

The payment panel uses `isFieldOnPage()` to check whether specific checkout fields are present on the page. Based on what's missing, it automatically adds fields inside the card section:

* **No `first_name`/`last_name` on page** → shows "Cardholder Name" input
* **No `billing_address`/`shipping_address` on page** → shows billing details (name, country, address)

You can use `isFieldOnPage()` in your own `template-if` conditions:

```html theme={null}
<template-if data-condition="!isFieldOnPage('checkout.customer.first_name')">
  <p>Name will be collected in the payment panel.</p>
</template-if>
```

The function checks for visible, non-hidden inputs bound via `data-template-value`, `data-ef-value`, or `name` attribute. Elements inside the payment panel itself are excluded to prevent self-referencing.

***

## Wallet (Apple Pay / Google Pay)

### Scope key

| Key | Type | Description |
| - | - | - |
| **`checkout.wallet_available`** | `{ applePay: bool, googlePay: bool }` | Which wallets are available on the current device/browser. Updated after CollectJS initializes. |

Use in template conditions to show wallet-specific content:

```html theme={null}
<template-if data-condition="checkout.wallet_available.applePay">
  <p class="wallet-hint">You can pay instantly with Apple Pay.</p>
</template-if>
<template-if data-condition="checkout.wallet_available.googlePay">
  <p class="wallet-hint">Google Pay is available on this device.</p>
</template-if>
```

### Wallet-first layout

Wallet buttons are rendered inside `<checkout-cc-panel>`. To make them prominent (e.g. for quiz funnels), place the payment panel **above** the shipping address section in your template. Both layouts use the same blocks and backend processing.

```html theme={null}
<!-- Email + phone first -->
<section>...</section>

<!-- Payment panel early = wallet buttons appear above shipping -->
<checkout-cc-panel></checkout-cc-panel>

<!-- Shipping address below -->
<section>...</section>

<!-- Submit button -->
<button type="submit" data-checkout-submit>COMPLETE ORDER</button>
```

See [How to design a checkout page — Example 2](/guides/how-to-design-a-checkout-page#example-2-wallet-first-checkout) for a full copy-paste template.

### `ef.checkout` API

For programmatic wallet control, a small JavaScript API is available on `window.ef.checkout`:

* **`ef.checkout.walletAvailable`** — same data as `checkout.wallet_available` scope key
* **`ef.checkout.payWithWallet(method)`** — triggers `'applePay'` or `'googlePay'` programmatically
* **`ef.checkout.onWalletComplete(callback)`** — fires after wallet payment attempt

Full reference: [Checkout functionality reference — `window.ef.checkout` API](/checkouts/checkout-functionality-reference#windowefcheckout-api).

***

## Summary

* Use **`is_single_product`** / **`is_cart`** and **`checkout.product_*`** vs **cartItems** for order summary.
* **Subscriptions:** `checkout.is_subscription` + `checkout.subscription` on single-product pages (server-side, available immediately); `item.is_subscription` + `item.subscription` on cart items.
* Prefer explicit subtotal keys: **`checkout.subtotal_before_discount`** / **`checkout.subtotal_after_discount`**.
* `checkout.subtotal` remains as a backward-compatible alias of `checkout.subtotal_after_discount`.
* Use **`_raw`** keys only for conditions/math or explicit formatting with `formatPrice`.
* Bind fields with **data-template-value**, use **data-checkout-error** and **errors** for validation.
* Coupon: **query.coupon**, **checkout.coupon**, **checkout.coupon\_message**; **data-apply-coupon**, **data-clear-coupon**.
* Bumps: **checkout.bump\_products**, **checkout.selectedBumpLines**; **data-bump-**\* attributes.
* Payment: **Pattern A** — **`<checkout-cc-panel></checkout-cc-panel>`** only; **Pattern B** — explicit gateway div with **`data-gateway`**, optional cardholder, **secure-card-element**.
* Wallet: **`checkout.wallet_visible`** (or **`checkout.wallet_available`**) for conditional content; **`ef.checkout.payWithWallet()`** for programmatic triggers; use **`<checkout-wallet force="true" />`** above the form for wallet-first layouts.


# Debugging
Source: https://docs.elasticfunnels.io/frontend-template-engine/debugging

Debug Window Templates tab, console debug flags, inspecting efScope, and verifying updates.

This page describes how to **debug** the frontend template engine: the **Debug Window Templates tab**, console debug flags, inspecting scope, and verifying updates.

***

## Debug Window — Templates tab

The easiest way to inspect template behavior is the **Templates** tab in the [Debug Window](/debugging/debug-window). It shows **template-if** results and lets you **inspect any element** for its template bindings and child tree.

<Info>
  **Open the Debug Window** with **Ctrl + Shift + F12** (Windows/Linux) or **Command + Shift + F12** (Mac) on an ElasticFunnels page, then click the **Templates** tab.
</Info>

When the **Templates** tab is active, the template processor sends **debug events** to the window (no URL or sessionStorage flag needed). There is no performance cost when the tab is closed.

### Events (New vs Previous)

The **Events** section shows:

| Section | Meaning |
| - | - |
| **New** | Template-if results from the **last action** (e.g. last scope update). Each entry shows condition(s), which branch was chosen (or "else"), and whether the run was skipped because the branch didn't change. |
| **Previous** | Earlier template-if runs from the same session. |

Each **template-if** event shows:

* The **condition** (or "(else)") and the **result** (e.g. `true`, `false`, branch index).
* **(unchanged)** when the engine skipped re-rendering because the selected branch was the same.

**template-if-error** events show the failing **condition** and the **error** message (e.g. from an invalid expression).

Use this when:

* A **template-if** branch never shows — check which condition is chosen and the result.
* You want to see whether template-if runs are being skipped (unchanged) after an action.

### Inspect element (Pick element)

**Inspect element** lets you click a node on the page and see its **template bindings** and **child tree**.

1. Click **Pick element**.
2. Click any element on the page (outside the debug window).
3. The panel shows:
   * **Template bindings** on that node: **data-condition**, **data-each**, **ef-text/data-ef-text**, **ef-value/data-ef-value/data-template-value**, **ef-src/ef-href/...**, **data-ef-var-path**, **data-ef-var-template**, **data-ef-cloak**, **data-ef-debug-if-condition**, **data-ef-debug-if-result**, and event bindings (**@click**, **data-ef-on:click**, etc.).
   * A **tree** of child nodes (tag, id, classes, and any template attributes).

When **scope updates** (e.g. after cart or form changes), the picked element’s panel **refreshes** so you see updated bindings and tree. Use **Clear pick** to deselect.

**data-ef-debug-if-condition** and **data-ef-debug-if-result** are set by the template engine when the Templates tab is open: they show which **template-if** condition and result produced that element. They appear in the bindings list and in the tree for nodes that are the first element of a rendered template-if branch.

***

## Console debug flags

The template processor (templateProcessor.js) also supports **console-only** debug flags. When set, it logs to the **browser console** with a **`[ef-template]`** prefix. These are independent of the Debug Window.

### 1. `efTemplateDebug`

Enables **general template debug** logs (e.g. directive runs, condition evaluation, var updates).

**How to enable:**

* **URL:** Add **`?efTemplateDebug`** to the page URL (e.g. `https://yoursite.com/checkout?efTemplateDebug`).
* **Session storage:** In the console or a script:
  ```javascript theme={null}
  sessionStorage.setItem('efTemplateDebug', '1');
  ```
  Reload. To disable: **`sessionStorage.removeItem('efTemplateDebug');`**

**What you’ll see:** Messages such as **getEffectiveContext**, **template-if evaluate**, **template-if: skip (branch unchanged)**, **template-foreach: skip (unchanged)**, **update: var-path** / **var-template** / **data-ef-text**, **runAllUpdates: start/done**, **updateElementsForPath**.

Use this when you need **console** output (e.g. in CI or without the Debug Window).

### 2. `efTemplateTraceContext`

Enables **stack traces** when **getEffectiveContext** is called (throttled to avoid flooding).

**How to enable:** Add **`?efTemplateTraceContext`** to the URL or set **`sessionStorage.setItem('efTemplateTraceContext', '1');`** and reload.

Use this when you need to see the **call stack** for context resolution.

***

## Inspecting scope

### Read `window.efScope`

In the browser console:

```javascript theme={null}
console.log(window.efScope);
```

Check that **cartItems**, **checkout**, **query**, **errors**, etc. are present and have the shape you expect. After an action (e.g. add to cart, apply coupon), inspect again and confirm the data changed.

### After an update

After something that should update the UI:

1. Confirm **efScope** has the new data.
2. If the UI did not update, verify the expected **efScope path actually changed** and that your template expressions reference that path (or a parent path).

***

## Verifying updates

### Manual trigger

To force a full re-run of the template engine (e.g. after editing **efScope** in the console):

```javascript theme={null}
if (typeof window.notifyScopeUpdated === 'function') {
  window.notifyScopeUpdated();
} else {
  window.dispatchEvent(new CustomEvent('ef-scope-updated'));
}
```

If the UI updates after this, the data was already correct and you likely had a path/expression mismatch.

### Path-scoped update

If you know the exact scope path that changed (e.g. **checkout.shipping\_same\_as\_billing**):

```javascript theme={null}
if (typeof window.notifyScopePathsUpdated === 'function') {
  window.notifyScopePathsUpdated(['checkout.shipping_same_as_billing']);
}
```

Then check that only the relevant part of the UI updates.

***

## Common issues

| Symptom | What to check |
| - | - |
| **`[[ ... ]]` stays as text** | Engine may not have run. Ensure **initTemplateScope()** runs (e.g. from main.js when template tags or bindings exist). Check for JS errors before init. Use **data-ef-cloak** and the Templates tab or **efTemplateDebug** to see if **runAllUpdates** runs. |
| **Wrong branch of template-if** | Open **Templates** tab and check **Events → New** for the condition and result. Or enable **efTemplateDebug** and look at **template-if evaluate**. Fix the condition or the data in **efScope**. |
| **Loop empty or wrong items** | Inspect **efScope.cartItems** (or the array in **data-each**). Ensure it’s an array and items contain the expected keys used in expressions. |
| **Form value not in scope** | Ensure the input has **ef-value/data-ef-value/data-template-value="path"** and that **path** is a dot path into **efScope**. Use **Pick element** to confirm the binding; after typing, confirm that path value changed in `window.efScope`. |
| **Bump/cart UI not updating** | Confirm the bump or cart plugin updates **efScope** values used by the template. Check **Templates → Events** or **efTemplateDebug** for **runAllUpdates** / **updateElementsForPath**. |

***

## Summary

* **Debug Window → Templates tab** — **Events** (New/Previous) show template-if results and errors; **Pick element** shows bindings and tree for any node. Refreshes on scope update. No URL flag needed when the tab is open.
* **Console flags** — **efTemplateDebug** (URL or sessionStorage) for `[ef-template]` logs; **efTemplateTraceContext** for getEffectiveContext stack traces.
* **Inspect** **window\.efScope** before and after actions to confirm data.
* **Optionally trigger** **notifyScopeUpdated()** or **notifyScopePathsUpdated(\[path])** manually during troubleshooting.

For full syntax and behavior, see [Overview](/frontend-template-engine/overview), [Syntax](/frontend-template-engine/syntax), [Cart](/frontend-template-engine/cart), and [Checkout](/frontend-template-engine/checkout).


# Limitations
Source: https://docs.elasticfunnels.io/frontend-template-engine/limitations-pitfalls

What the frontend template engine does not do, common mistakes, and how to avoid them.

This page covers **limitations** of the frontend template engine (compared to full frameworks like Vue or Alpine) and **common pitfalls** with fixes.

## Quick reference: common pitfalls

| Symptom | Cause | Fix |
| - | - | - |
| Wrong or double currency | Using **formatPrice** on already-formatted values | Use **`[[ checkout.total ]]`**, **`[[ item.price ]]`** as-is; see [Functions](/frontend-template-engine/built-in-functions#price-display-when-to-use-formatprice-vs-as-is) |
| **`{{ x }}`** not replaced | Frontend engine uses **`[[ ]]`** only | Use **`[[ expression ]]`** for frontend; **`{{ }}`** is backend |
| UI doesn't update after changing data | Path/expression mismatch or data shape issue | Verify the changed `efScope` path matches your binding expression and item/object shape |
| Single-product block wrong/missing | Using **cartItems\[0]** | Use **checkout.product\_title**, **checkout.product\_image**, etc.; see [Checkout](/frontend-template-engine/checkout) |
| Flash of raw **`[[ ... ]]`** | Content visible before engine runs | Add **data-ef-cloak** to elements; use CSS to hide **`[data-ef-cloak]`** |
| **template-else** not working | Else not a sibling of **template-if** | Put **template-else** / **template-else-if** as immediate siblings after **template-if** |
| Checkout validation not showing | Missing error container or wrong id | Use **data-checkout-error="\<id>"** and **data-template-value** per [Checkout](/frontend-template-engine/checkout#form-fields-and-validation) |
| Bump toggle/style not working | Missing data attributes | Use **data-bump-code**, **data-bump-checkbox**, **data-bump-toggle**; see [Cart](/frontend-template-engine/cart#order-bumps-on-checkout) |
| Select options missing on Safari/iOS | **template-foreach** inside **select** | Use inline **data-each** on **option** directly; see [Syntax — Inline data-each](/frontend-template-engine/syntax#inline-data-each-on-regular-elements) |

***

## Limitations

### Not a full framework

* **No virtual DOM** — Updates are reactive and path-scoped, but this is not a component framework with diffed virtual DOM.
* **Element-level lifecycle only** — You have **`@mounted`**, **`@unmounted`**, and **`@visible`** per element (see [Bindings & Events](/frontend-template-engine/bindings-forms-events#lifecycle--visibility-directives)), plus **`window.ef.template.watch(...)`** and **`window.ef.template.computed(...)`** for scope-driven reactions. There is no full component composition API (no slots, no scoped components, no `props`).
* **No standalone template-else** — A **`<template-else>`** must be a **sibling** of a **`<template-if>`** (or follow **template-else-if**). You cannot have “else only” without an if.

### Reactivity model

* **`window.efScope` is reactive** — changing nested keys/arrays updates bound UI automatically.
* **Path-scoped updates still exist** — internals and advanced callers can use path-scoped updates for high-frequency flows; most custom code does not need manual notify calls.

### Expression evaluation

* Expressions run in a **merged context** (scope + loop vars) using **`with(scope) { return (expression); }`**. Very complex expressions or ones that rely on strict mode / undeclared variables can be fragile. Prefer simple paths and small expressions.
* **Reserved names** in event handlers: **`$event`**, **`event`**, **`$el`**, **`$target`** are injected; avoid using them as scope keys if you need to read them from global scope.

### Checkout and cart data

* **`checkout`** is only set on **checkout pages**. Any template that uses **`checkout.*`** on a non-checkout page may see **undefined**. Guard with **`<template-if data-condition="checkout">`** in shared components.
* **`query`** (URL params) is only available if the app sets **`efScope.query`** at init (e.g. via **`syncQueryToScope()`**). Conditions like **`query.coupon`** will not work otherwise.

***

## Common pitfalls

### 1. Using `formatPrice` on already-formatted values

**Mistake:** **`[[ formatPrice(checkout.total, checkout.currency) ]]`** or **`[[ formatPrice(item.price, item.currency) ]]`**.

**Why it’s wrong:** **`checkout.total`**, **`item.price`**, **`item.total`**, **`bump.price`**, **`line.price`** are already **formatted** currency strings. Passing them to **formatPrice** can produce wrong or duplicated symbols.

**Fix:** Use **`[[ checkout.total ]]`**, **`[[ item.price ]]`**, **`[[ item.total ]]`**, **`[[ bump.price ]]`**, **`[[ line.price ]]`** as-is. Use **formatPrice** only for **raw** values (e.g. **`checkout.total_raw`**, **`bump.price_raw`**) when you need to display a number.

***

### 2. Using `{{ }}` in frontend templates

**Mistake:** Writing **`{{ variable }}`** in HTML that is processed by the **frontend** engine.

**Why it’s wrong:** **`{{ }}`** is reserved for the **backend** Template Engine. The frontend engine only replaces **`[[ ]]`**.

**Fix:** Use **`[[ expression ]]`** for frontend token interpolation. For attribute bindings, prefer `ef-*`/`data-ef-*` (e.g. `ef-text="checkout.total"`).

<Warning title="Expecting the wrong path to update UI">
  **Mistake:** Changing one path but binding to another (for example mutating `checkout.items` while template reads `cartItems`, or expecting `item.quantity` aliases outside foreach context).

  **Why it breaks:** Reactivity runs, but your binding expression may not reference the changed path or expected data shape.

  **Fix:** Keep data keys and template expressions aligned (e.g. `cartItems` with `item in cartItems` and `item.*` inside that loop). Inspect `window.efScope` and Pick Element bindings in the Templates debug tab.
</Warning>

<Warning title="Using cartItems[0] in single-product block">
  **Mistake:** In the **single-product** layout (one product, big image + title), using **`cartItems[0].name`** or **`cartItems[0].image`**.

  **Why it’s fragile:** The app may not guarantee **cartItems\[0]** on single-product checkout; the canonical data for that view is **checkout.product\_title**, **checkout.product\_image**, etc.

  **Fix:** Use **`<template-if data-condition="is_single_product">`** and **checkout.product\_**\* keys; use **cartItems** only in the **cart** block. See [Checkout — Order summary](/frontend-template-engine/checkout#order-summary-single-product-vs-cart).
</Warning>

<Warning title="Missing data-ef-cloak">
  **Mistake:** No **data-ef-cloak** on blocks that contain **`[[ ... ]]`** or **template-if** content, so users see raw brackets or the wrong branch until the processor runs.

  **Fix:** Add **`data-ef-cloak`** to elements that should be hidden until the template engine has run. The engine removes this attribute after processing. On ElasticFunnels-hosted pages the cloak stylesheet is already in `<head>` and hides **`[data-ef-cloak]`** plus every engine tag — **template-if**, **template-else-if**, **template-if-else**, **template-else**, **template-foreach**, **template-vars**, **template-set**, **template-partial** / **partial**. If you embed the engine elsewhere, hide that full list; a tag left out of it paints its raw content on first paint and then disappears.
</Warning>

<Warning title="Wrong template-else structure">
  **Mistake:** Putting **`<template-else>`** inside **`<template-if>`**, or using a tag like **`<template-if-else>`**.

  **Fix:** **template-else** and **template-else-if** must be **siblings** of **template-if**, immediately after it. Structure:

  ```html theme={null}
  <template-if data-condition="...">...</template-if>
  <template-else-if data-condition="...">...</template-else-if>
  <template-else>...</template-else>
  ```
</Warning>

<Warning title="Checkout fields without error container">
  **Mistake:** Checkout inputs without **`data-checkout-error="fieldId"`** container, or **id** / **data-template-value** not matching the field list the backend expects.

  **Fix:** Each checkout field needs **id**, **name**, **data-template-value**, and **`<div class="form-error" data-checkout-error="<id>"></div>`**. Use exact ids and paths from the spec. See [Checkout — Form fields](/frontend-template-engine/checkout#form-fields-and-validation).
</Warning>

<Warning title="template-foreach inside select (Safari / iOS)">
  **Mistake:** Wrapping `<option>` elements in `<template-foreach>` inside a `<select>`:

  ```html theme={null}
  <select name="billing_country">
    <template-foreach data-each="c in checkout.countries">
      <option :value="c.value">[[ c.label ]]</option>
    </template-foreach>
  </select>
  ```

  **Why it breaks:** Safari and iOS strip unknown/custom elements from `<select>`. The `<template-foreach>` tag is removed by the browser before the template engine runs, so no options render.

  **Fix:** Use inline `data-each` directly on the `<option>` tag:

  ```html theme={null}
  <select name="billing_country" data-template-value="checkout.customer.billing_country">
    <option data-each="opt in checkout.countries" data-ef-value="opt.value" data-ef-cloak>[[ opt.label ]]</option>
  </select>
  ```

  The server-side processor auto-converts `<template-foreach>` inside `<select>` in page templates, but client-side generated HTML (e.g. plugins) must use the inline form directly.
</Warning>

<Warning title="Bump checkboxes without data attributes">
  **Mistake:** Bump checkboxes/labels without **data-bump-checkbox**, **data-bump-toggle**, or **data-bump-code**, so the bump-products plugin cannot toggle or style them.

  **Fix:** Use **`data-bump-code="[[ bump.code ]]"`** on the card, **`data-bump-checkbox="[[ bump.code ]]"`** and **`value="[[ bump.code ]]"`** on the checkbox, and **`data-bump-toggle="[[ bump.code ]]"`** on the label. Same code on both “add” and “remove” states.
</Warning>

***

## Summary

* **Limitations:** No virtual DOM/component lifecycle; **template-else** needs a sibling **template-if**; **checkout** and **query** are context-specific.
* **Pitfalls:** Don’t use **formatPrice** on formatted values; use **\[\[ ]]** not  for frontend; keep data paths aligned with bindings; use **checkout.**\* for single-product summary; use **data-ef-cloak** where needed; keep **template-if/else** structure and checkout/bump attributes as specified; never use **template-foreach** inside **select** — use inline **data-each** on **option** instead (Safari/iOS).

Next: [Debugging](/frontend-template-engine/debugging).


# Overview
Source: https://docs.elasticfunnels.io/frontend-template-engine/overview

Introduction to the ElasticFunnels frontend template processor: Alpine-like scope, custom tags, and reactive UI.

The **Frontend Template Engine** is a client-side processor that runs in the visitor’s browser. It lets you build HTML that reacts to data (cart items, checkout totals, URL parameters, etc.) and updates when that data changes—without a full page reload.

<Note>
  This documentation covers the **frontend** template system only. A separate **backend** Template Engine (server-side) uses different syntax (e.g. `{{ }}`, `@if`, `@foreach`). You can use both on the same page: backend for initial render, frontend for live updates.
</Note>

<Warning>
  The frontend engine is the **last** of four layers that rewrite a page, and it is the only one that runs in the browser. Split-test and dynamic containers were already filled on the server, before this engine existed — so a `<template-if>` wrapped around a container does **not** stop the container from being filled. Read [Rendering pipeline](/pages/rendering-pipeline) before mixing layers.
</Warning>

## When to use it

Use the frontend template engine when:

* **Content depends on the visitor** — Cart items, item count, order total, selected bumps, coupon status.
* **You want live updates** — Adding to cart, changing quantity, applying a coupon, or toggling bumps should update the UI immediately.
* **You control the layout** — You design the structure (rows, labels, buttons) in the page builder; only the data is dynamic.

If the content is the same for everyone and does not change after load (e.g. a fixed headline), use normal content or [page variables](/pages/page-variables) instead.

## How it works

1. **Data lives in `window.efScope`** — The app (and cart/checkout plugins) put data here: `cartItems`, `checkout`, `query`, etc.
2. **You use custom tags and expressions** — `<template-if>`, `<template-foreach>`, `[[ path ]]`, `ef-text`, `@click`, and similar.
3. **Scope changes update automatically** — `window.efScope` is reactive. Changing values (including nested values and arrays) re-evaluates conditions, re-renders loops, and refreshes bindings.

There is no virtual DOM; reactivity is **scope- and event-driven** with automatic change detection.

## Quick start

### 1. Put reactive data in `window.efScope`

```html theme={null}
<script>
  window.efScope = window.efScope || {};
  window.efScope.items = [
    { code: 'A1', name: 'Product Alpha', price: 29.99, quantity: 2 },
    { code: 'B2', name: 'Product Beta', price: 14.50, quantity: 1 }
  ];
  window.efScope.currency = 'USD';
</script>
```

### 2. Use custom tags and expressions in your HTML

```html theme={null}
<h2 data-ef-cloak>Cart</h2>

<template-if data-condition="items.length > 0">
  <p data-ef-cloak>You have [[ items.length ]] items.</p>
</template-if>
<template-else>
  <p class="muted" data-ef-cloak>Your cart is empty.</p>
</template-else>

<template-foreach data-each="item in items">
  <div class="cart-line" data-ef-cloak>
    <span>[[ item.name ]]</span>
    <span>Qty: [[ item.quantity ]]</span>
    <span>[[ formatPrice(item.price * item.quantity, currency) ]]</span>
  </div>
</template-foreach>
```

### 3. Change scope directly (auto reactive)

```javascript theme={null}
window.efScope.items.push({ code: 'C3', name: 'New Item', price: 9.99, quantity: 1 });
window.efScope.currency = 'USD';
```

* **`data-ef-cloak`** — Hides the element until the template processor has run (removes the attribute when done). Use it to avoid a flash of raw `[[ ... ]]` or the wrong branch. On ElasticFunnels-hosted pages the platform already ships this stylesheet in `<head>`: it hides `[data-ef-cloak]` plus **every** engine tag — **template-if**, **template-else-if**, **template-if-else**, **template-else**, **template-foreach**, **template-vars**, **template-set**, **template-partial** / **partial**. If you embed the engine elsewhere, hide the full list; a tag left out of it paints its raw content on first paint and then disappears.

On offer/checkout pages, the application and plugins (cart, checkout, bumps) usually manage `efScope` for you.

## What the engine provides

| Feature | Purpose |
| - | - |
| **`[[ expression ]]`** | Insert a value (or expression) in text or attributes. |
| **`<template-if>` / `<template-else-if>` / `<template-else>`** | Show one block based on a condition. |
| **`<template-foreach>`** | Repeat a block once per item in an array. |
| **`ef-text` / `ef-html`** | Bind an element’s text or HTML to an expression (`data-` aliases also supported). |
| **`ef-href` / `ef-title` / `ef-alt` / `ef-placeholder`** | One-way attribute bindings from scope to DOM attributes. |
| **`ef-value` / `data-template-value`** | Two-way form binding (Vue v-model style) for inputs, selects, textareas. |
| **`@click` (and other events)** | Run an expression when the user clicks (or triggers another event). |
| **`:checked` / `:disabled` / `:value`** | One-way bindings from scope to DOM properties. |
| **`@mounted` / `@unmounted` / `@visible`** | Element lifecycle and viewport-visibility handlers (with `.once` / `.every` modifiers for `@visible`). |
| **Built-in functions** | `formatPrice`, `cartCount`, `cartSubtotal`, `upper`, `lower`, `titleCase`, etc. |
| **`ef.template.watch/computed`** | Runtime API for watchers and computed values via `window.ef.template`. |

## Builder-friendly bindings

For page-builder work, attribute bindings are often easier to preview and edit than mixed text tokens:

```html theme={null}
<!-- token style -->
<h2>[[ checkout.product_title ]]</h2>

<!-- binding style -->
<h2><span ef-text="checkout.product_title">Product Title</span></h2>
```

You can add these directly from the **Data Attributes** panel (right sidebar) when a component is selected.

Details and examples are in [Syntax](/frontend-template-engine/syntax), [Scope & Data](/frontend-template-engine/scope-and-data), [Bindings & Events](/frontend-template-engine/bindings-forms-events), [Functions](/frontend-template-engine/built-in-functions), [Cart](/frontend-template-engine/cart), and [Checkout](/frontend-template-engine/checkout).

## Relation to other docs

* **Frontend Template Engine** (this section) — Full reference: syntax, scope, bindings, cart, checkout, limitations, debugging.
* **Backend Template Engine** — Documented in [Backend Template Engine](/backend-template-engine/overview) (server-side `{{ }}`, `@if`, `@foreach`, etc.).

Next: [Syntax](/frontend-template-engine/syntax).


# Scope & Data
Source: https://docs.elasticfunnels.io/frontend-template-engine/scope-and-data

window.efScope, checkout.*, cartItems, query.*, and how the template engine resolves expressions.

All expressions in the frontend template engine are evaluated against a **merged context**: the global scope (`window.efScope`) plus any local context (e.g. loop variables). This page describes what data lives where and how to use it safely.

## Global scope: `window.efScope`

The single source of truth for reactive data is **`window.efScope`**. The application and plugins (cart, checkout, bumps) populate and update it.

* **Initialization:** The template engine ensures `window.efScope` exists when `initTemplateScope()` runs (e.g. from main.js). Cart and checkout plugins then set `cartItems`, `checkout`, etc.
* **Updates:** `efScope` is reactive. After code changes `efScope`, the DOM updates automatically.

### Typical top-level keys

| Key | Description |
| - | - |
| **`cartItems`** (or **`items`**) | Array of cart line items. Prefer **`cartItems`** in new templates. |
| **`checkout`** | Checkout data: totals, customer fields, bump products, coupon, etc. Only set on checkout pages. |
| **`query`** | URL query parameters as an object (e.g. `query.coupon`, `query.p`, `query.bumps`). Must be populated at init (e.g. via `syncQueryToScope()`). |
| **`currency`** | Default currency (e.g. `USD`) when not overridden by `checkout.currency`. |
| **`is_cart`** / **`is_single_product`** | Booleans set by the app to distinguish multi-item checkout vs single-product checkout. |
| **`errors`** | Object keyed by field id: `{ [fieldId]: message }`. Used for checkout validation messages. |
| **`mode`** | Helper object with e.g. `item_count`, `has_query_product`, `is_cart`, `is_single_product`. |

<Warning>
  **`checkout`** is only defined on checkout pages. On other pages, `checkout` may be `undefined`. Guard with `<template-if data-condition="checkout">` if you use `checkout.*` in shared templates.
</Warning>

***

## Cart: `cartItems` / `items`

* **`cartItems`** — Preferred name for the array of cart line items (used on checkout and cart UI).
* **`items`** — Alias; same data in many contexts.
* On checkout pages the same list is also exposed as **`checkout.cart`** and **`checkout.items`**.

Each **item** typically has:

| Property | Description |
| - | - |
| **`code`** | Product/cart line code (used for qty +/- and remove). |
| **`name`** | Product name. |
| **`image`** | Product image URL (for thumbnails). |
| **`quantity`** | Quantity. |
| **`price`** | Unit price — **already formatted** (e.g. "\$29.00"). Use as-is in `[[ item.price ]]`. |
| **`total`** | Line total — **already formatted**. Use `[[ item.total ]]`; do not call `formatPrice(lineTotal(item), ...)`. |
| **`currency`** | Currency code for the line. |

Cart plugin (e.g. cart.js) builds this structure and provides formatted `price` and `total`; the template engine does not re-format them.

***

## Checkout: `checkout.*`

On **checkout pages**, `efScope.checkout` holds everything needed for the order summary, form, and payment. For full checkout-specific docs (totals, fields, coupon, bumps, payment panel), see [Checkout](/frontend-template-engine/checkout).

### Totals (formatted + raw, mode-agnostic)

The same totals schema is available in both checkout modes (`is_single_product` and `is_cart`), so templates can reuse one price-summary layout.

Formatted keys (display):

* **`checkout.product_price`**, **`checkout.retail_price`**
* **`checkout.bump_total`**
* **`checkout.subtotal_before_discount`**
* **`checkout.discount_total`**
* **`checkout.subtotal_after_discount`**
* **`checkout.subtotal`** (legacy alias of `subtotal_after_discount`)
* **`checkout.shipping`**, **`checkout.tax`**, **`checkout.total`**

Raw keys (conditions/math):

* **`checkout.product_price_raw`**, **`checkout.retail_price_raw`**
* **`checkout.bump_total_raw`**
* **`checkout.subtotal_before_discount_raw`**
* **`checkout.discount_total_raw`**
* **`checkout.subtotal_after_discount_raw`**
* **`checkout.subtotal_raw`** (legacy alias of `subtotal_after_discount_raw`)
* **`checkout.shipping_raw`**, **`checkout.tax_raw`**, **`checkout.total_raw`**

Use formatted keys directly in templates; use raw keys for conditions like `checkout.tax_raw > 0`.

### Single-product vs cart layout

* **`is_single_product`** — One product; show hero image + title block. Use **`checkout.product_image`**, **`checkout.product_title`**, **`checkout.product_price`**, **`checkout.retail_price`** (and optionally **`product_code`**, **`product_description`**). Do **not** use `cartItems[0]` in that block.
* **`is_cart`** — Multiple items; show list with `<template-foreach data-each="item in cartItems">` and **`[[ item.image ]]`**, **`[[ item.name ]]`**, **`[[ item.total ]]`**, etc.

### Bumps

* **`checkout.bump_products`** — Full list of bump products (each has **`code`**, **`name`**, **`description`**, **`price`** formatted, **`price_raw`** numeric, **`image`** URL, **`added`** boolean).
* **`checkout.selectedBumpLines`** — Array of selected bumps: **`code`**, **`name`**, **`price`** (formatted), **`price_raw`**.

Use **`[[ bump.price ]]`** and **`[[ line.price ]]`** for display; do not pass them to `formatPrice`. Use **`price_raw`** only for conditions or when you explicitly format a raw number. Use **`bump.added`** for conditional blocks and for **@click** add/remove patterns (e.g. **`<button @click="bump.added = true">`** / **`<button @click="bump.added = false">`**); use **`ef-src="bump.image"`** for the bump image (with a placeholder **`src`**).

### Coupon

* **`checkout.coupon`** — When applied: **`applied`**, **`code`**, **`name`**, **`value_formatted`**, **`fixed_value`**, **`pct_value`**, **`discount`**.
* **`checkout.coupon_message`** — Error message from validation (e.g. invalid code). Show with `<template-if data-condition="checkout.coupon_message">` and `[[ checkout.coupon_message ]]`.
* **URL coupon:** Use **`query.coupon`** to detect a coupon from the URL; use **`checkout.coupon`** for the applied details after the app auto-applies.

### Customer and form fields

* **`checkout.customer.*`** — Paths used with **`data-template-value`** for two-way binding: e.g. **`checkout.customer.email`**, **`checkout.customer.shipping_first_name`**, **`checkout.customer.billing_first_name`**.
* **`checkout.shipping_same_as_billing`** — Boolean; when true, shipping address block can be hidden and a short message shown instead.
* **`checkout.countries`**, **`checkout.usStates`** — Arrays of **`{ value, label }`** for country/state `<select>` options.

***

## URL parameters: `query.*`

**`query`** should be an object built from `window.location.search` (e.g. via `syncQueryToScope()` at init). Each query parameter is a key; e.g. **`query.coupon`**, **`query.p`**, **`query.bumps`**.

Use **`query.*`** for URL-driven visibility:

```html theme={null}
<template-if data-condition="query.coupon">
  <p>Automatically applied coupon: [[ checkout.coupon.code ]]</p>
</template-if>
```

If the app does not set `efScope.query`, conditions like `query.coupon` will be undefined and the block will not show.

***

## Effective context and `mode`

The engine merges **caller context** (e.g. from a loop) with **`window.efScope`** to form the **effective context** for each expression. It also adds:

* **`mode`** — Object with **`item_count`**, **`has_query_product`**, **`is_cart`**, **`is_single_product`**.
* **`is_cart`**, **`is_single_product`** — Convenience booleans on the root of the merged context.

So you can write **`<template-if data-condition="is_single_product">`** and **`<template-if data-condition="is_cart">`** without touching `checkout` directly.

***

## Runtime API: watch and computed

The frontend API also exposes Vue-like helpers at `window.ef.template`:

```javascript theme={null}
const stop = window.ef.template.watch('checkout.total', (newValue, oldValue) => {
  console.log('total changed', oldValue, '->', newValue);
}, { immediate: true });

const searchUrl = window.ef.template.computed('links.googleSearch', (ctx) => {
  const q = ctx?.search ?? '';
  return `https://google.com/?s=${encodeURIComponent(q)}`;
});

// use in template:
// <a ef-href="links.googleSearch">Search</a>

// cleanup:
stop();
searchUrl.stop();
```

***

## Summary

* **Data lives in `window.efScope`**; expressions see global scope + loop/block context.
* **Reactivity is automatic** when `efScope` values change.
* **Cart:** Use **`cartItems`** (or **`items`**); each **item** has **`price`**, **`total`** (formatted), **`code`**, **`name`**, **`image`**, **`quantity`**.
* **Checkout:** Use **`checkout.*`** for totals, bumps, coupon, customer; use **formatted** keys for display and **`_raw`** only when you need numbers or `formatPrice`.
* **URL:** Use **`query.*`** after the app has set **`efScope.query`** (e.g. via `syncQueryToScope()`).
* **Layout:** Use **`is_single_product`** and **`is_cart`** to choose between single-product summary and cart list.

Next: [Bindings & Events](/frontend-template-engine/bindings-forms-events).


# Syntax
Source: https://docs.elasticfunnels.io/frontend-template-engine/syntax

template-if, template-else-if, template-else, template-foreach, template-set, template-vars, and [[ expression ]] in the frontend template engine.

This page describes the **directives** and **expression syntax** of the frontend template engine.

<Info>
  Use **`[[ ]]`** for frontend expressions. **`{{ }}`** is reserved for the backend Template Engine. Both can appear on the same page.
</Info>

## Conditionals: `template-if`, `template-else-if`, `template-else`

Show one block among several based on a JavaScript expression evaluated in the current scope.

### `template-if`

* **Attribute:** `data-condition="expression"`
* **Behavior:** When the expression is **truthy**, the element’s inner HTML is rendered; otherwise it is not. The `<template-if>` element itself is replaced by that content.

```html theme={null}
<template-if data-condition="cartItems.length > 0">
  <p>You have [[ cartCount(cartItems) ]] items.</p>
</template-if>
```

### Sibling `template-else`

A **`<template-else>`** immediately after a `<template-if>` (or after a chain of `template-else-if`) is the fallback when no condition matches. It has **no** `data-condition`.

```html theme={null}
<template-if data-condition="cartItems.length > 0">
  <p>You have items in your cart.</p>
</template-if>
<template-else>
  <p class="muted">Your cart is empty.</p>
</template-else>
```

### `template-else-if`

Chain multiple conditions. The **first** matching branch is shown; if none match, the optional `template-else` is shown.

```html theme={null}
<template-if data-condition="cartItems.length > 1">
  <div class="card">Cart has multiple items.</div>
</template-if>
<template-else-if data-condition="cartItems.length === 1">
  <div class="card">You have one item.</div>
</template-else-if>
<template-else>
  <div class="card muted">No items.</div>
</template-else>
```

<Warning>
  **`template-else` always needs a preceding `template-if`.** There is no standalone “else only” block. Use `template-else-if` for the middle branches, not a tag like `template-if-else`.
</Warning>

### What you can use in `data-condition`

* **Dot paths:** `checkout.coupon.applied`, `query.coupon`, `items.length`
* **Comparisons:** `cartItems.length > 0`, `item.quantity === 1`
* **Functions:** `cartCount(cartItems) > 0`, `checkout.selectedBumpLines && checkout.selectedBumpLines.length > 0`
* **Literals:** `data-condition="true"` or `data-condition="false"` are supported

In HTML attributes, **escape** characters that would break the attribute: use **`&gt;`** for `>`, **`&amp;`** for `&`, **`&lt;`** for `<` (e.g. **`data-condition="cartItems.length &gt; 1"`**).

Expressions run in a context that includes `window.efScope` and any loop variable (e.g. `item` inside a `template-foreach`).

***

## Loops: `template-foreach`

Repeat a block once per element in an array (or iterable). The element is replaced by the repeated content.

### Preferred form: `data-each`

```html theme={null}
<template-foreach data-each="item in cartItems">
  <div class="cart-line">
    <span>[[ item.name ]]</span>
    <span>[[ item.quantity ]]</span>
    <span>[[ item.total ]]</span>
  </div>
</template-foreach>
```

* **`item`** — Variable name for the current element (you can choose any name).
* **`cartItems`** — Expression that must evaluate to an array (or iterable) in scope.

### Optional index

Use **`(item, i) in array`** or **`item, i in array`** to get a zero-based index:

```html theme={null}
<template-foreach data-each="(item, i) in cartItems">
  <div class="cart-line">
    <span>[[ i + 1 ]]. [[ item.name ]]</span>
  </div>
</template-foreach>
```

### Inline `data-each` on regular elements

Instead of wrapping content in a `<template-foreach>` tag, you can place `data-each` directly on the repeated element itself. This is **required** for `<option>` elements inside a `<select>` — Safari and iOS do not allow custom elements like `<template-foreach>` inside `<select>`, so the options will not render.

```html theme={null}
<select name="billing_country" data-template-value="checkout.customer.billing_country">
  <option data-each="opt in checkout.countries" data-ef-value="opt.value" data-ef-cloak>[[ opt.label ]]</option>
</select>
```

Use `data-ef-value` to bind the option's `value` attribute and `data-ef-cloak` to hide the template row until the engine expands it.

<Warning>
  **Do not use `<template-foreach>` inside `<select>`.** Safari and iOS strip unknown elements from `<select>`, so `<option>` elements wrapped in `<template-foreach>` will not appear. Always use inline `data-each` on the `<option>` tag directly.
</Warning>

### Aliases and fallbacks

* **`data-for`** — Alias for `data-each` (same meaning).
* **Legacy:** You can use **`data-item`**, **`data-index`**, and **`data-array`** instead of `data-each` if needed. **`data-item`** and **`data-array`** can also be used **together with** `data-each` when the engine expects them (e.g. for internal loop variable names), as in some production checkout templates.

### Empty arrays

When the array is empty, the loop renders nothing. Some integrations support an optional **empty content** (e.g. “Your cart is empty”) via configuration; the default behavior is to output no nodes.

### Scope inside the loop

Inside the block, **`item`** (and `i` if you declared it) are in scope. You can also access parent scope (e.g. `checkout.currency`, `cartItems`). Nested **`<template-if>`** and **`<template-foreach>`** are supported.

***

## Variables: `template-set` and `template-vars`

### `template-set`

Define a **local variable** for the template. The element is **removed** after processing; only the variable is set in the current context.

* **`data-variable="name"`** — Variable name (single segment, e.g. `total` or `label`).
* **`data-value="expression"`** — Expression to evaluate; result is stored in `name`.

```html theme={null}
<template-set data-variable="lineTotal" data-value="item.price * item.quantity"></template-set>
<p>Line total: [[ lineTotal ]]</p>
```

Use when you need to reuse a computed value or keep markup readable.

### `template-vars` / `<template data-ef-vars>`

Enables **`[[ expression ]]`** in the **content** of the element without requiring a wrapping `template-if` or `template-foreach`. The element is **replaced** by its inner content; that content is then processed (conditions, loops, and variable replacement run on it).

Use **`<template-vars>`** or **`<template data-ef-vars>`** when you have a block where the only dynamic part is `[[ ... ]]` and you want to avoid an extra conditional.

<Note>
  **`var.*` is backend-only, by design.** Brand variables belong to the server-side template engine — print them with `{{ var.offer_name }}`. They are deliberately never copied into `window.efScope` (the browser gets the values a page chose to print, not the brand's variable set), so `[[ var.something ]]` has nothing to resolve against.

  To use one client-side, hand it over explicitly: the server prints the value, the page stores it under a name you choose.

  ```html theme={null}
  <script>
    window.efScope = window.efScope || {};
    window.efScope.offerName = {{ var.offer_name | json | raw }};
  </script>

  <p>[[ offerName ]]</p>
  ```

  See [Rendering pipeline](/pages/rendering-pipeline#var-is-a-backend-facility).
</Note>

### `template-component` — does not exist

<Warning>
  There is **no frontend component include.** `<template-component data-component-name="…">` appears in some older reference tables, but no engine resolves it — not the frontend processor, not the backend template engine, not the page pipeline. It reaches the browser as an inert unknown element and, being normally empty, renders **nothing at all with no error**.

  Include a component with the backend directive **`@component("code", { key: value })`** instead. See [Rendering pipeline](/pages/rendering-pipeline#template-component-does-not-exist).
</Warning>

***

## Expressions: `[[ ... ]]`

**`[[ expression ]]`** is replaced by the result of the expression, evaluated in the current scope (global scope + loop/block context).

### Where it works

* **Text nodes:** `Price: [[ item.price ]]`
* **Attribute values:** `src="[[ item.image ]]"`, `data-code="[[ item.code ]]"`, `required="[[ f.required ? 'required' : '' ]]"`
* **Anywhere** inside processed template content (e.g. inside `template-if` or `template-foreach`)

For cart/checkout control attributes, use **`data-code="[[ item.code ]]"`** so the plugin receives the actual product code string. Unquoted **`data-code="item.code"`** may still be supported by the engine in some contexts.

### What you can write inside `[[ ]]`

* **Dot paths:** `item.name`, `checkout.total`, `checkout.customer.email`
* **Expressions:** `item.price * item.quantity`, `item.open ? 'Hide' : 'Show'`
* **Function calls:** `formatPrice(item.price, currency)`, `upper(item.name)`, `cartCount(cartItems)`

Functions available in expressions include [built-in helpers](/frontend-template-engine/built-in-functions) and any registered via `registerTemplateFunction`.

### Examples

| You write | Meaning | Example result |
| - | - | - |
| `[[ item.name ]]` | Current item’s name | "1 Bottle" |
| `[[ item.price ]]` | Unit price (often pre-formatted) | "\$69.00" |
| `[[ item.total ]]` | Line total (price × qty) | "\$552.00" |
| `[[ checkout.total ]]` | Checkout total (formatted) | "\$99.00" |
| `[[ formatPrice(amount, currency) ]]` | Format a number as currency | "\$49.99" |
| `[[ item.open ? 'Hide details' : 'Show details' ]]` | Ternary | "Show details" |

<Warning>
  **Checkout and cart display values** (e.g. `checkout.total`, `item.total`, `item.price`, `bump.price`) are usually **already formatted** as currency strings. Use them as-is (e.g. `[[ checkout.total ]]`). Do **not** pass them to `formatPrice()` again. Use **`formatPrice`** only for **raw** values (e.g. `checkout.total_raw`, `bump.price_raw`) when you need to display a number. See [Built-in functions](/frontend-template-engine/built-in-functions) and [Limitations and pitfalls](/frontend-template-engine/limitations-pitfalls).
</Warning>

***

## Attribute binding shortcuts (`ef-*`)

For many UI components, attribute bindings are easier to maintain than inline token strings:

```html theme={null}
<span ef-text="checkout.product_title">Product Title</span>
<img ef-src="checkout.product_image" ef-alt="checkout.product_title" />
<a ef-href="links.checkout" ef-title="checkout.product_title">Continue</a>
<input ef-placeholder="checkout.customer.email_placeholder" />
```

Supported aliases include `ef-text`, `ef-html`, `ef-src`, `ef-href`, `ef-title`, `ef-alt`, `ef-placeholder`, and `ef-value` (plus `data-` forms).

These can be added from the page builder **Data Attributes** panel (right sidebar) when an element is selected.

***

## Cloaking

To avoid a flash of raw **`[[ ... ]]`** or the wrong branch before the template engine runs:

* **`[data-ef-cloak]`** — Add this attribute to elements that should be hidden until processed. The engine may remove it after processing. Include CSS: **`[data-ef-cloak] { display: none !important; }`**.
* **Template tags** — Include CSS that hides the custom elements until processed: **`template-foreach`**, **`template-if`**, **`template-else`**, **`template-set`** with **`display: none !important`**.
* In some deployments, **`data-frontend-template="true"`** is used on **`template-if`**, **`template-else`**, and **`template-foreach`** to mark frontend-processed blocks.

***

## Processing order

The engine runs directives in a fixed order:

1. **templateVars** — Unwrap `<template-vars>` / `<template data-ef-vars>` so inner `[[ ]]` can be processed.
2. **set** — Process `<template-set>` (set variables, remove elements).
3. **foreach** — Expand `<template-foreach>` (in a one-shot process path) or re-render mounted foreach on update.
4. **if** — Expand `<template-if>` (and sibling else-if/else) or re-render mounted if on update.
5. **vars** — Replace remaining `[[ ... ]]` in text and attributes.

On **initial load**, `template-if` and `template-foreach` are **mounted**: the original tags are replaced by comment anchors and an update function is registered. When reactive scope changes happen, those functions re-evaluate and only affected parts of the DOM update.

Next: [Scope & Data](/frontend-template-engine/scope-and-data).


# Checkout Redirect Behavior
Source: https://docs.elasticfunnels.io/funnels/checkout-redirect-behavior

Understanding default checkout redirects and domain-funnel assignment for purchase flows

When customers purchase from pages that aren't properly assigned to a funnel, the system automatically redirects them to a default thank you page instead of following your intended funnel flow. Understanding and configuring this behavior is crucial for maintaining your sales funnel continuity.

## Default Redirect Behavior

### When Default Redirects Occur

The system redirects customers to a generic thank you page (`/thank-you`) in these situations:

1. **Page Not in Expected Funnel**: The customer purchases from a VSL page, homepage, or landing page that isn't part of any active funnel
2. **No Active Funnel on Domain**: There's no funnel assigned to the current domain the customer is purchasing from
3. **Missing Funnel Parameter**: The customer accessed the page without the `?f=funnel_code` parameter and no default funnel is set

### Why This Happens

This default behavior serves as a **fallback mechanism** to ensure:

* Customers always receive purchase confirmation
* The checkout process completes successfully
* No customers are left without a post-purchase experience
* Business continuity even when funnel configuration is incomplete

<Warning>
  While the default redirect ensures checkout completion, it bypasses your intended upsell sequences, tracking, and custom post-purchase flows. Proper domain-funnel assignment is essential for optimal conversion rates.
</Warning>

## Domain-Funnel Assignment

### Understanding Domain Assignment

Every funnel can be assigned to one or more domains to control which funnel handles purchases from that domain.

**Key Concepts:**

* **Domain Assignment**: Links a specific domain to a funnel
* **Default Funnel**: The funnel that handles all traffic on a domain without explicit funnel parameters
* **Funnel Parameter**: The `?f=funnel_code` URL parameter that explicitly specifies which funnel to use

### How to Assign Domains to Funnels

#### Method 1: Through Funnel Settings (Recommended)

1. Go to **Funnels** in your dashboard
2. Find and select the funnel you want to configure
3. Click **Edit Funnel**
4. In the funnel editor, go to the **Domains** section
5. Click **Add Domain**
6. Enter your domain (e.g., `yoursite.com`)
7. Choose assignment type:
   * **Explicit Only**: Requires `?f=funnel_code` parameter
   * **Default for Domain**: Handles all traffic without parameters
8. Check **"Make Default"** if you want this funnel to handle all traffic on this domain
9. Save your configuration

#### Method 2: Through Settings (Alternative)

1. Go to **Settings** → **Domains** section
2. Click **Add Domain** or find an existing domain
3. Configure domain settings and assign to funnels
4. Set default funnel assignments as needed

#### Important Notes

* **A funnel can be on multiple domains**: You can assign the same funnel to several domains
* **Multiple default assignments**: A funnel can be set as default on multiple domains
* **Flexible access**: Some domains can require the `?f=funnel_code` parameter while others have the funnel as default

### Multiple Domain Configuration

You can assign multiple domains to the same funnel:

**Example Setup:**

* Main domain: `yoursite.com` (set as default)
* Backup domain: `backup-domain.com` (set as default)
* Testing domain: `test.yoursite.com` (explicit only)

## The Funnel Parameter System

### Understanding `?f=funnel_code`

The funnel parameter (`?f=`) explicitly tells the system which funnel to use:

**Examples:**

* `https://yoursite.com/page?f=main-funnel` - Uses "main-funnel"
* `https://yoursite.com/page?f=upsell-sequence` - Uses "upsell-sequence"
* `https://yoursite.com/page` - Uses default funnel (if set) or triggers default redirect

### When to Use Funnel Parameters

#### **Required Scenarios:**

* **Multiple funnels per domain**: When you have different products/campaigns
* **Testing new funnels**: Before making them default
* **Affiliate-specific funnels**: Different flows for different traffic sources
* **Campaign-specific flows**: Unique sequences for different marketing campaigns

#### **Optional Scenarios:**

* **Single funnel per domain**: Set as default to avoid parameter requirement
* **Simple product flows**: When you only have one purchase path
* **General traffic**: Most visitors can use the default funnel

### Getting Funnel Links

To get a properly formatted funnel link with the correct parameter:

1. Go to **Funnels** in your dashboard
2. Find the funnel you want in the list
3. Click **"Generate Tracking Link"** for that funnel
4. This will provide you with the complete URL including the proper `?f=funnel_code` parameter
5. Use this link for your marketing campaigns, affiliate links, or anywhere you need to ensure visitors enter the specific funnel

### Best Practices for Parameter Usage

**For Traffic Sources:**

```
Facebook Ads: https://yoursite.com/page?f=facebook-funnel&source=fb
Google Ads: https://yoursite.com/page?f=google-funnel&source=google
Affiliate Links: https://yoursite.com/page?f=affiliate-funnel&aff=partner123
```

**For Product Lines:**

```
Product A: https://yoursite.com/page?f=product-a-funnel
Product B: https://yoursite.com/page?f=product-b-funnel
Premium: https://yoursite.com/page?f=premium-funnel
```

## Configuration Examples

### Example 1: Single Product Website

**Scenario**: One main product with one sales funnel

**Setup:**

1. Create one funnel: "main-sales-funnel"
2. Assign your domain: `yoursite.com`
3. **Set as default**: ✅ Checked
4. **Result**: All purchases automatically use the correct funnel

### Example 2: Multi-Product Website

**Scenario**: Multiple products with different upsell sequences

**Setup:**

1. Create multiple funnels:
   * "weight-loss-funnel"
   * "muscle-gain-funnel"
   * "supplements-funnel"
2. Assign all to domain: `fitnesssite.com`
3. **Set default**: Choose your main product funnel
4. **Use parameters** for other products:
   * Weight loss: `?f=weight-loss-funnel`
   * Muscle gain: `?f=muscle-gain-funnel`
   * Supplements: `?f=supplements-funnel`

### Example 3: Multiple Domains

**Scenario**: Different brands on different domains

**Setup:**

1. **Brand A Funnel**:
   * Domain: `brand-a.com` (default)
   * Handles all Brand A traffic
2. **Brand B Funnel**:
   * Domain: `brand-b.com` (default)
   * Handles all Brand B traffic
3. **Testing Funnel**:
   * Domain: `test.brand-a.com` (explicit only)
   * Requires `?f=test-funnel` parameter

## Troubleshooting Common Issues

### Issue: Customers Going to Default Thank You Page

**Symptoms:**

* Customers complete purchase but see generic thank you page
* Missing expected upsells or post-purchase flow
* No funnel tracking data for purchases

**Solutions:**

1. **Check domain assignment**: Ensure your domain is assigned to a funnel
2. **Verify default setting**: Make sure a default funnel is set if not using parameters
3. **Test with parameters**: Try accessing with `?f=your-funnel-code`
4. **Review purchase links**: Ensure buy buttons are on funnel-assigned pages
5. **Use generated links**: Get proper funnel links via "Generate Tracking Link" in the funnel list

### Issue: Wrong Funnel Executing

**Symptoms:**

* Customers enter wrong upsell sequence
* Incorrect post-purchase flow
* Wrong tracking attribution

**Solutions:**

1. **Check parameter conflicts**: Multiple funnel parameters can cause conflicts
2. **Review default funnel**: Default might be overriding intended funnel
3. **Verify URL structure**: Ensure funnel parameters are correctly formatted
4. **Test explicit parameters**: Use specific `?f=` parameters to override defaults
5. **Use generated links**: Generate proper tracking links to ensure correct funnel codes

### Issue: Funnel Parameter Not Working

**Symptoms:**

* Funnel parameter ignored
* Always defaults to same funnel
* Parameter appears in URL but doesn't change behavior

**Solutions:**

1. **Verify funnel code**: Check that the funnel code in parameter matches exactly
2. **Check funnel status**: Ensure the target funnel is active and published
3. **Review domain configuration**: Confirm funnel is assigned to the current domain
4. **Clear cache**: Browser or CDN caching might serve old configuration
5. **Use generated links**: Get the correct funnel code via "Generate Tracking Link"

## Testing Your Configuration

### Step 1: Test Default Behavior

1. Visit your page without any parameters: `https://yoursite.com/page`
2. Complete a test purchase
3. Verify you enter the correct funnel flow

### Step 2: Test Explicit Parameters

1. Visit with funnel parameter: `https://yoursite.com/page?f=your-funnel-code`
2. Complete a test purchase
3. Confirm the specified funnel executes

### Step 3: Test Edge Cases

1. **Invalid funnel code**: `?f=nonexistent-funnel` (should fall back to default)
2. **Empty parameter**: `?f=` (should use default funnel)
3. **Multiple parameters**: `?f=funnel1&f=funnel2` (should use first valid one)

### Verification Checklist

* [ ] Domain is assigned to intended funnel
* [ ] Default funnel is set (if desired)
* [ ] Test purchases complete successfully
* [ ] Correct upsell sequences execute
* [ ] Analytics track properly
* [ ] All purchase links work correctly

## Best Practices

### Domain Management

1. **Set clear defaults**: Every active domain should have a default funnel
2. **Document assignments**: Keep track of which domains use which funnels
3. **Regular testing**: Test purchase flows on all domains monthly
4. **Monitor analytics**: Watch for unexpected redirect patterns

### Funnel Parameter Strategy

1. **Use descriptive codes**: Make funnel codes clear and memorable
2. **Document parameter usage**: Track which campaigns use which parameters
3. **Test all combinations**: Verify every parameter/domain combination works
4. **Monitor performance**: Compare conversion rates across different funnels
5. **Use generated links**: Always use "Generate Tracking Link" to get correct funnel codes

### Maintenance & Updates

1. **Regular audits**: Review domain-funnel assignments quarterly
2. **Test after changes**: Always test purchase flows after configuration changes
3. **Monitor customer feedback**: Watch for complaints about unexpected experiences
4. **Update documentation**: Keep team informed of configuration changes

<Note>
  Set the domain-funnel assignment before you send traffic. The right assignment keeps checkout redirects predictable and makes conversion tracking easier to trust.
</Note>

## Related Documentation

* [Create Funnel](/funnels/create-funnel) - Basic funnel creation and setup
* [Query Parameters](/funnels/query-parameters) - Advanced parameter usage and conditions
* [Split Testing](/funnels/split-testing) - Testing different funnel flows
* [Thank You Pages](/forms/thank-you-pages) - Customizing post-purchase experiences
* [Buy Links](/products/buy-links) - Setting up purchase buttons and links


# Create a Funnel
Source: https://docs.elasticfunnels.io/funnels/create-funnel

Step-by-step guide to creating your first funnel from scratch

Learn how to start a fresh funnel, assign domains, and organize your funnel steps.

1. From your main dashboard, click on "Funnels"
2. Click the "Create New Funnel" button
3. Enter a funnel name
4. Assign one or more domains (optional: set as default for a domain)
5. Proceed to the builder interface
6. Click "Add Node" to add your first funnel step (e.g., a page or a redirect)
7. Connect your nodes to define the journey
8. Click "Save" to store your changes

<Note>
  Rearranging nodes: In the funnel builder, drag nodes to reposition them. Use the "Rearrange" control to auto-layout when the canvas gets messy. Save, then reload to confirm the layout persists.
</Note>

## Tips

* Choose a descriptive funnel name that reflects your campaign or product
* Setting a default domain reduces setup steps later
* Start simple with just a few nodes, you can always add more complexity later
* Test your funnel flow before going live


# Dynamic Content
Source: https://docs.elasticfunnels.io/funnels/dynamic-content

Swap a section of a page for a saved component, driven by Page Events conditions

A **dynamic container** is a slot on a page whose contents can be replaced at render time with a saved component. The slot itself carries no logic — a **Dynamic Content** node in [Page Events](/funnels/page-events) decides which component goes in it, and under what conditions.

Use it for affiliate-specific pricing, region-specific offers, source-specific hero sections, or any "same page, different block" scenario.

<Note>
  Dynamic containers and split-test containers are **different tags with different purposes**. `<dynamic-container>` swaps content based on a **condition you write**. `<split-test>` swaps content based on a **traffic split**. See [Split Testing](/funnels/split-testing).
</Note>

***

## Core concepts

* **One container = one slot.** A container marks a single location on the page. To vary the header *and* the footer you need two containers.
* **Variants are saved components.** You cannot swap a raw div or section — convert it to a component first. The node stores the component's **code**.
* **The contents of the container are the default.** Whatever you author inside the tag renders whenever no Dynamic Content node fills it.
* **One node fills one container.** Four possible banners in one slot means one container, one component per alternative, and one Dynamic Content node per condition branch.

***

## Step 1 — Create the components

Dynamic content works by swapping **saved components**.

1. Build the section you want to show (a specific pricing table, a banner, a video block).
2. Right-click the element and select **Transform to Component**.
3. Once saved you can delete it from the page — unless it is also your default content.
4. Repeat for every variation.

***

## Step 2 — Add the container

### In the page builder

Right-click the element (or the area where the slot should live) and choose **Wrap in → Dynamic Container**, or drag the **Dynamic Content** block onto the page. Then set the **Dynamic Container Name** trait — that is the label you will pick from in Page Events.

Anything left inside the container is its default content.

### On a coded page

```html theme={null}
<dynamic-container id="hero-banner" name="Hero Banner">
  <!-- Default content, shown when no Dynamic Content node fills this slot -->
  <div class="banner default-banner">Standard Offer</div>
</dynamic-container>
```

| Attribute | Required | Description |
| - | - | - |
| `id` | Yes | What the Page Events node stores and what the renderer matches on. Must be unique on the page. |
| `name` | Yes | Human-readable label shown in the Page Events container dropdown. |

<Warning>
  **On coded pages the attribute order is fixed.** The container list is built by scanning the page HTML for `<dynamic-container id="…" name="…">` — `id` must come first, immediately followed by `name`, both in double quotes, with nothing between them. Written any other way the container still renders and can still be filled at runtime, but it **will not appear in the Page Events dropdown**, so you cannot select it in the UI.
</Warning>

### Listing container IDs

The dropdown is populated from:

```
GET /api/brands/{brand}/pages/{page}/component-type/dynamic-container
```

```json theme={null}
[ { "id": "hero-banner", "name": "Hero Banner", "type": "dynamic-container" } ]
```

The `id` is exactly what the node stores in its `container` field. The same endpoint serves `split-test-container` and `form`.

<Tip>
  Click the **reload icon** next to the container or component dropdown in the node to refresh the list after editing and saving the page. If a previously selected container is no longer found, the node resets to *Select dynamic container* — that is your signal that the `id` changed or the tag is no longer being detected.
</Tip>

***

## Step 3 — Fill it from Page Events

Open **Manage Page Events** and add a **Dynamic Content** node (`dynamic_container`).

| Field | Required | Description |
| - | - | - |
| **Container** | Yes | The `<dynamic-container>` to fill. The node warns *"Container is required"* until set. |
| **Component** | Yes | The component to render into it, chosen by code. The node warns *"Component is required"* until set. |

Connect it beneath whatever decides that this variant applies — an entry node for an unconditional swap, or the appropriate output of a condition.

```mermaid theme={null}
flowchart LR
  E[Loaded] --> C{Query Parameter Condition<br/>aff_id is 42}
  C -->|Output 1 · true| D[Dynamic Content<br/>container: hero-banner<br/>component: affiliate-42-banner]
  C -->|Output 2 · false| N[ default content renders ]
```

The node runs on the **server**, before the HTML is sent, and it continues down its output afterwards — so you can chain further actions behind it.

Field detail: [Node Reference → Dynamic Content](/funnels/page-events-nodes#dynamic-content).

***

## How it renders

When a Dynamic Content node targets a container and both `container` and `component` are set, the renderer replaces the **entire** `<dynamic-container>` element — including the default content — with a div carrying the original `id`, holding the resolved component:

```html theme={null}
<!-- Authored -->
<dynamic-container id="hero-banner" name="Hero Banner">
  <div class="banner default-banner">Standard Offer</div>
</dynamic-container>

<!-- Intermediate -->
<div id="hero-banner"><component type="affiliate-42-banner"></component></div>

<!-- Final output -->
<div id="hero-banner">
  <div data-cid="982"><!-- HTML of affiliate-42-banner --></div>
</div>
```

The component's CSS and interactions are pulled into the page at the same time.

**If nothing fills the container** — no node targets it, the `id` does not match, or the node is missing its container or component — the tag and its default content are left exactly as authored.

<Note>
  The `name` attribute plays no part in matching at render time; matching is on `id` alone. `name` exists so a human can find the container in the Page Events dropdown.
</Note>

***

## Examples

### Affiliate-specific banner

```html theme={null}
<dynamic-container id="hero-banner" name="Hero Banner">
  <div class="banner default-banner">Standard Offer</div>
</dynamic-container>
```

In Page Events:

1. **Loaded** → **Referred By Affiliate** (select the affiliate)
2. Output 1 → **Dynamic Content** → container `Hero Banner`, component `affiliate-42-banner`
3. Output 2 → nothing; the default banner renders

### Two independent slots on one page

```html theme={null}
<dynamic-container id="headline-slot" name="Headline Slot">
  <h1>Default Headline</h1>
</dynamic-container>

<dynamic-container id="footer-disclaimer-slot" name="Footer Disclaimer">
  <p>Default disclaimer text</p>
</dynamic-container>
```

Each slot needs its own Dynamic Content node. They can hang off the same condition — chain them, since the node continues after filling its container.

### Country-specific pricing

1. **Loaded** → **Is From Country** with `CA` selected
2. Output 1 → **Dynamic Content** → container `pricing`, component `pricing-cad`
3. Output 2 → **Is From EU** → Output 1 → **Dynamic Content** → container `pricing`, component `pricing-eur`
4. Everything else falls through to the container's default content

***

## Use cases

* **Affiliate-specific content** — different pricing or bonuses per referral source
* **Location-based offers** — region-specific copy, currency or compliance text
* **Traffic source targeting** — a hero that matches the ad the visitor clicked
* **Customer vs prospect** — a different block for people who have already bought
* **Whitelisted vs compliant** — pair with the whitelist nodes for review-safe content

***

## The `<component>` tag

`<component>` embeds a saved component directly, with no Page Events involved. This is what a filled dynamic container becomes internally, and you can use it anywhere on a page.

```html theme={null}
<component type="general-footer"></component>
```

| Attribute | Required | Description |
| - | - | - |
| `type` | Yes | The code of the component to embed. |

Renders as:

```html theme={null}
<div data-cid="[component_id]">
  <!-- HTML of the component -->
</div>
```

If the code is not found, the server renders an inline error so the problem is visible rather than silent:

```html theme={null}
<ef-error>Component <u>my-component-code</u> was not found.</ef-error>
```

<Note>
  Component lookup tolerates the `custom-` prefix: `general-footer-2` and `custom-general-footer-2` resolve to the same component when one of them exists. Components that embed themselves are not re-expanded, so a self-referencing component will not loop.
</Note>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="The container dropdown is empty">
    On builder pages, check the block is a **Dynamic Container** and that its **Dynamic Container Name** trait is filled in. On coded pages, check the tag is written exactly as `<dynamic-container id="…" name="…">` with `id` immediately before `name`. Save the page, then click the reload icon on the node.
  </Accordion>

  <Accordion title="The component dropdown is empty or missing my component">
    Save the page after creating components, then click the reload icon next to the component dropdown. Components must be saved as components — raw sections do not appear.
  </Accordion>

  <Accordion title="Default content renders instead of the component">
    Confirm the node's branch actually ran (the [Debug Window](/debugging/debug-window) → Page Events tab shows which path was taken), and that the node has **both** a container and a component set. A node missing either field is skipped silently.
  </Accordion>

  <Accordion title="The wrong slot got swapped">
    Two containers sharing the same `id` will both be matched. Make `id` unique per page.
  </Accordion>

  <Accordion title="I need traffic split between versions, not a condition">
    That is a component split test, not dynamic content. See [Split Testing](/funnels/split-testing).
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup>
  <Card title="Node Reference" href="/funnels/page-events-nodes" />

  <Card title="Page Events" href="/funnels/page-events" />

  <Card title="Split Testing" href="/funnels/split-testing" />

  <Card title="Containers" href="/pages/containers" />

  <Card title="Script Rule" href="/funnels/script-rule" />

  <Card title="Query Parameters" href="/funnels/query-parameters" />
</CardGroup>


# Exit Popups
Source: https://docs.elasticfunnels.io/funnels/exit-popups

Capture leaving visitors with exit intent popups

An exit popup appears when a user's mouse moves toward leaving the page, giving you a final opportunity to engage them.

## Setup

### Step 1: Create the Popup

1. Go to "Pages" → "Advanced" → "Popups"
2. Click "Create Popup" and give it a name
3. Select a base template if needed

### Step 2: Configure Exit Intent

1. Return to the page events builder for the page
2. Click "Add Node" and select the "Exit Intent" node
3. Add a "Popup" node and connect it to the "Exit Intent" node

## Best Practices

* Keep your exit popup message compelling but not intrusive
* Offer genuine value (discount, bonus content, etc.)
* Test different popup designs and messages
* Don't show exit popups on every page - be strategic
* Consider mobile user experience (exit intent works differently on mobile)


# Funnel Split Testing
Source: https://docs.elasticfunnels.io/funnels/funnel-split-testing

Split test entire pages or branches in your funnel

Funnel-level split testing lets you test different pages or branches of your funnel. It works like component split testing, but instead of selecting a component inside a page, you select a target page or another node in the funnel.

## Setup

### Step 1: Add a Split Test to your funnel

1. Open your funnel in the builder
2. Click "Add Node" where you want to branch traffic
3. Select "Split Test" as the node type

### Step 2: Create your variants

1. For each variant, choose a target:
   * **Page**: Send visitors to a specific page node
   * **Node**: Send visitors to any existing node (e.g., an alternate VSL path)
2. Set traffic percentages (must total 100%)
3. Name variants clearly (e.g., "VSL A", "VSL B")

### Step 3: Connect and save

1. Connect the split test node to each target page/node
2. Ensure downstream nodes (purchase, upsells, declines) are connected
3. Click "Save" and reload to confirm layout

## Best Practices

* Keep one variable per test (page vs. branch) for clean attribution
* Run tests long enough to reach statistical significance
* Use clear variant names and document the hypothesis
* Monitor performance and disable losing variants promptly

<Note>
  If you only need to test content inside a single page (like headlines or videos), use **component split testing** instead: [Split Testing](/funnels/split-testing).
</Note>

## Troubleshooting

* Variants not receiving traffic: verify percentages total 100% and connections are valid
* Wrong page loading: check that each variant points to the intended page/node
* Missing upsell flow: ensure variant targets connect to the correct purchase/upsell nodes


# Page Events
Source: https://docs.elasticfunnels.io/funnels/page-events

The flow graph attached to a page: how it is stored, when each node runs, and how to wire it

Page Events is a **flow graph attached to a page**. You connect triggers, conditions and actions, and the platform runs them — some before the HTML is sent, some in the visitor's browser after load. It is what powers whitelisting, dynamic content, component split tests, exit popups, merchant switching and video CTAs.

Open it from **Pages → (your page) → Manage Page Events**.

<CardGroup>
  <Card title="Node reference" icon="list-tree" href="/funnels/page-events-nodes">
    Every node type, its fields, and its wiring constraints
  </Card>

  <Card title="The graph model" icon="diagram-project" href="#the-graph-model">
    Nodes, connections, entry views, and how it is stored
  </Card>

  <Card title="Server vs browser" icon="server" href="#server-vs-browser">
    Which nodes run before the page is sent, and which run after
  </Card>

  <Card title="Patterns" icon="puzzle-piece" href="#common-patterns">
    Worked examples and troubleshooting
  </Card>
</CardGroup>

***

## The graph model

A page's events are a **directed graph of nodes**. Every node has:

* a **type** (`data.type`) — the real identity of the node, e.g. `script_rule`, `dynamic_container`, `component_split_test`
* a **node code** (`data.node_code`) — a short stable identifier used by analytics and split-test reporting
* **input and output pins** — `input_1`, `output_1`, `output_2`… Connections are stored on both ends, so a link appears in the source node's `outputs.output_N.connections` and in the target's `inputs.input_M.connections`.
* a **position** on the canvas (`pos_x`, `pos_y`)

### Reading a branch

Outputs are ordered, and the order is the meaning:

* **Output 1** — the first pin. For a condition node this is the **true / Yes** branch.
* **Output 2** — the second pin. For a condition node this is the **false / No** branch.

Every node except **Sequence** follows **one connection per output**. If you need two actions on the same branch, either chain them (most actions have an output that continues the flow) or use a **Sequence** node and add an output per action.

### Entry views

Every flow starts from an **entry node** (the node labelled *Loaded*). A page may have several.

Each entry node appears as a **View** in the left rail of the builder. You can name it (pencil icon), reorder the list by dragging, and each view remembers its own camera position on the canvas. The order is saved as `entry_views_order`.

<Warning>
  Views are a **canvas organisation feature, not a routing feature.** At render time the platform collects the children of **every** entry node and runs them all — it does not choose one view. `entry_views_order` affects the builder only. If two views must be mutually exclusive, put the choice behind a condition.
</Warning>

### Global page events

Alongside per-page events, a brand has one **Global Page Events** graph — open it with **Manage Global Page Events** in the builder toolbar. Global events are merged into every page's flow and are **ordered ahead of the page's own events**. Use them for brand-wide concerns (cloaking, IP rules, universal tagging) instead of copying the same nodes onto every page.

### Where it is stored

Page events are loaded and saved through:

```
GET  /api/brands/{brand}/pages/{page}/events
POST /api/brands/{brand}/pages/{page}/events
```

Use `global` in place of the page ID for the brand-wide graph. Save is **POST only — there is no PUT**, and these are session-authenticated app endpoints, not public API-key endpoints.

The response body is the builder's export:

```jsonc theme={null}
{
  "drawflow": { "Home": { "data": {
    "1": {
      "id": 1,
      "name": "entry",
      "data": { "type": "entry", "value": "3202", "node_code": "…", "view_name": "Main" },
      "inputs":  {},
      "outputs": { "output_1": { "connections": [ { "node": "2", "output": "input_1" } ] } },
      "pos_x": 960, "pos_y": 2154
    }
  } } },
  "canvas_x": -1290,
  "canvas_y": -1867,
  "entry_views_order": [1, 5, 9]
}
```

<Note>
  When a page has no events yet, `GET .../events` returns **`200` with an empty body** — not `{}` and not `404`. Handle that case if you are reading the endpoint programmatically.
</Note>

On save, the platform compiles the graph into a flattened execution tree, assigns `node_code`s where missing, and creates or updates the split-test records referenced by any `split_test` / `component_split_test` node.

***

## Server vs browser

Each node declares where it can run. The platform splits your graph into a **server pass** and a **browser payload**.

| | Server (before the HTML is sent) | Browser (after the page loads) |
| - | - | - |
| **Use for** | routing, whitelisting, cloaking, content selection, merchant/checkout setup | scroll, video, exit intent, popups, DOM changes, pixels |
| **Examples** | Script Rule, Query Parameter Condition, Dynamic Content, Component Split Test, Load Another Page, Set Merchant, Block Request | On Exit Intent, When scrolled to, Video checks, Show Popup, Show/Hide Element, Execute Javascript on Client |

**How the split is decided:** a branch is sent to the browser if it — or anything below it — is a browser-only node. Certain nodes are pinned to the server even when they have browser children (`script_rule`, `page_variant`, `product_check`, `cloaking_house`, `is_whitelisted`, `url_redirect`, `set_variable`, `set_checkout_bumps`, `block_request`, `split_test`, `execute_automation`). When such a node picks a branch that belongs to the browser, the server hands that branch over to the browser payload and stops there.

<Warning>
  **Order matters and it is one-directional.** Server → browser works (`script_rule` → `client_script`). Browser → server does not (`exit_intent` → `script_rule`). Put every server-side decision before the first browser node on a path.
</Warning>

Browser events are serialised into the page as `window.page_events` and executed by the funnel runtime script. **Save your flow and reload the page** to pick up changes.

***

## Node catalogue

The full list — purpose, fields, inputs/outputs and constraints for every node — lives in the [Page Events Node Reference](/funnels/page-events-nodes). Quick orientation:

<AccordionGroup>
  <Accordion title="Flow control">
    **Loaded** (entry) · **Router** · **Sequence** · **Stop Next Events Execution**
  </Accordion>

  <Accordion title="Conditions — server">
    **Script Rule** · **Query Parameter Condition** · **Is Customer** · **Has Purchased Any Upsell** · **Referred By Affiliate** · **Is From Country / State / EU / Timezone** · **Is Using VPN/Proxy** · **Is Whitelisted?** · **Has Tag** · **Cloaking.house** · **Product Check** (+ Match Product / Match All)

    All of these compile to a script and take the **true** branch on Output 1.
  </Accordion>

  <Accordion title="Conditions & triggers — browser">
    **On Exit Intent** · **On Form Success** · **On Add To Cart** · **CTA: On Shown** · **When scrolled to** · **Scroll Check** · **Element In View** · **If Showed CTA** · **If Added To Cart** · **Video: Is muted / On Pause / On Goal Reached / Progress Check**
  </Accordion>

  <Accordion title="Content & routing">
    **Dynamic Content** · **Load Another Page** · **Redirect to Page** · **Redirect to URL** · **Show Popup** · **Show / Hide Element** · **Show / Hide Video CTA** · **Wait Seconds** · **Execute Javascript on Client**
  </Accordion>

  <Accordion title="Session, commerce & security">
    **Tag User** · **Whitelist visitor** · **Mark visitor as NOT whitelisted** · **Set Merchant** · **Clear Merchant** · **Set Checkout Page** · **Set Checkout Bumps** · **Set Variable** · **Execute Automation on Customer** · **Block Request**
  </Accordion>

  <Accordion title="Split testing">
    **Component Split Test** · **Split Test** · **Traffic Distribution** · **Component**

    See [Split Testing](/funnels/split-testing) for the full wiring.
  </Accordion>
</AccordionGroup>

<Note>
  Nodes are filtered by permission. If a node is missing from **Add Node**, your role probably lacks its permission — for example split-test nodes need `split_tests.create` / `split_tests.update`, and **Set Checkout Bumps** only appears on pages flagged as checkout pages.
</Note>

***

## Common patterns

### Whitelisting from a URL parameter

```mermaid theme={null}
flowchart LR
  A[Loaded] --> B{Query Parameter Condition<br/>vtID is not empty}
  B -->|Output 1 · true| C[Whitelist visitor]
  B -->|Output 2 · false| D[Compliant content]
```

1. **Loaded** → **Query Parameter Condition** (`vtID`, operator `is not empty`)
2. Output 1 → **Whitelist visitor** (`0` minutes = permanent)
3. Output 2 → leave empty, or route to compliant content

### Blocking traffic outside a country

1. **Loaded** → **Is From Country** with `US` selected
2. Output 1 (true) → leave empty
3. Output 2 (false) → **Block Request** with your message

<Warning>
  Attach **Block Request** to the specific output of the condition. Dropping it directly under the entry node blocks **every** visitor.
</Warning>

### Merchant by traffic source

1. **Loaded** → **Query Parameter Condition** (`source` `is` `partner1`) → Output 1 → **Set Merchant**
2. Output 2 → a second **Query Parameter Condition** (`source` `is` `partner2`) → Output 1 → **Set Merchant**
3. Output 2 → nothing; the domain default applies

Use **Clear Merchant** to explicitly return to the domain default.

### Video: pause, then show the CTA

1. **Video: On Pause** → **Video: Progress Check** (`30`%)
2. Output 1 → **Wait Seconds** (`2`) → **Show Video CTA** (with **Scroll to CTA** if you want the page to jump)
3. Output 2 → nothing

### Swapping content for one affiliate

1. **Loaded** → **Referred By Affiliate** (pick the affiliate)
2. Output 1 → **Dynamic Content** → container `pricing`, component `affiliate-pricing`
3. Output 2 → nothing; the container's default content renders

See [Dynamic Content](/funnels/dynamic-content).

***

## Best practices

* **Prefer the purpose-built condition over a Script Rule.** *Is From Country*, *Is Using VPN/Proxy*, *Query Parameter Condition* and friends are readable at a glance and self-documenting. Save Script Rule for logic they cannot express.
* **Combine instead of nesting.** One *Is From Country* with three countries beats three chained nodes. If a chain would be three levels deep, write one Script Rule.
* **Put server decisions first.** Everything that routes, cloaks or selects content should run before the first browser node.
* **Name your split tests and variants.** Those names are what you read in analytics later.
* **Use views to keep the canvas readable**, not to separate behaviour — every view runs.

<Tip>
  Use **Rearrange** in the toolbar to auto-layout the canvas, then save. Camera position is stored per view, so each one reopens where you left it.
</Tip>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Nothing happens on the page">
    Save the flow and reload the page — browser nodes are shipped with the HTML, so an unsaved change is not live. Then check that the branch is actually reachable: a node wired to nothing, or attached below a condition whose other branch is being taken, will not run.
  </Accordion>

  <Accordion title="A branch runs when it should not">
    Check which output you attached to. **Output 1 is true, Output 2 is false.** This trips people up most often with *Block Request* and *Load Another Page*.
  </Accordion>

  <Accordion title="Only one of my two actions runs">
    Every node except **Sequence** allows one connection per output. Add a **Sequence** node and give it an output per action, or chain the actions.
  </Accordion>

  <Accordion title="A node refuses to connect">
    The builder enforces parent restrictions. **Component** only attaches to **Traffic Distribution**; **Traffic Distribution** only to a split-test node; **Video: Is muted** only below **On Exit Intent**; **Product Check: Match Product/All** only below **Product Check**. See [wiring rules](/funnels/page-events-nodes#wiring-rules).
  </Accordion>

  <Accordion title="Everything after my split test is ignored">
    A **Component Split Test** ends its branch after swapping the container. Wire follow-up work before it, not after it.
  </Accordion>

  <Accordion title="A condition always takes the same path">
    Open the [Debug Window](/debugging/debug-window) → **Page Events** tab. It shows each Script Rule's result, execution time, console output and the full data it received. Remember that parameter names and values are case-sensitive.
  </Accordion>

  <Accordion title="Split-test or container dropdown is empty">
    The container list is read from the page itself. On builder pages the container must be a **Split Test Container** / **Dynamic Container** block with its name trait filled in; on coded pages the tag must be written as `<split-test id="…" name="…">` with `id` immediately before `name`. Click the reload icon next to the dropdown after saving the page.
  </Accordion>
</AccordionGroup>

***

## Related docs

<CardGroup>
  <Card title="Node Reference" href="/funnels/page-events-nodes" />

  <Card title="Script Rule" href="/funnels/script-rule" />

  <Card title="Query Parameters" href="/funnels/query-parameters" />

  <Card title="Dynamic Content" href="/funnels/dynamic-content" />

  <Card title="Split Testing" href="/funnels/split-testing" />

  <Card title="Sequence Nodes" href="/funnels/sequence-nodes" />

  <Card title="Exit Popups" href="/funnels/exit-popups" />

  <Card title="Window API" href="/funnels/window-api" />

  <Card title="Page Variants" href="/pages/page-variants" />

  <Card title="Debug Window" href="/debugging/debug-window" />
</CardGroup>


# Page Events Node Reference
Source: https://docs.elasticfunnels.io/funnels/page-events-nodes

Every Page Events node type: purpose, fields, inputs/outputs, and wiring constraints

This is the complete reference for every node available in the **Page Events** builder. For the graph model, entry views, and execution order, start with [Page Events](/funnels/page-events).

Each node is identified internally by a **type code** (`data.type`). The type code is what the AI flow generator, the API and the runtime use — the label in the UI is just the display name.

***

## How to read this reference

Every node entry shows:

| Field | Meaning |
| - | - |
| **Type** | The internal `data.type` value. |
| **In / Out** | Number of input pins and output pins. `0` outputs means the branch ends there. |
| **Runs on** | `Server` = evaluated before the HTML is sent. `Browser` = evaluated in the visitor's browser after load. Some nodes run in both places. |
| **Module / permission** | The node only appears in **Add Node** if your role has this permission. |
| **Fields** | Keys stored on the node. |

**Condition nodes always have 2 outputs:**

* **Output 1** = condition was **true** (the Yes path)
* **Output 2** = condition was **false** (the No path)

***

## Wiring rules

The builder enforces four connection rules. If a connection is rejected, one of these is why.

<AccordionGroup>
  <Accordion title="only_on — allowed parents">
    Some nodes may only be attached below specific node types. For example **Component** (`component_split_test_component`) is `only_on: split_test_weight`, so it can only hang off a Traffic Distribution node.

    When resolving the parent, the builder **skips pass-through nodes** (see `middleman` below) and compares against the first real parent. Generic condition nodes also match on their `base_type` of `script_rule`, which is why nodes restricted to `script_rule` accept **Is From Country**, **Query Parameter Condition**, and the other generated-script conditions too.
  </Accordion>

  <Accordion title="one_of_type — one of this kind per output">
    When a node is marked `one_of_type`, you cannot attach two nodes of the same type to the same output of the parent. The builder removes the second connection and shows *"You can't connect more than one \<type> node to this node"*.
  </Accordion>

  <Accordion title="max_per_output — fan-out limit">
    Most nodes allow only **one** connection per output pin. To run several actions from one branch, use a **Sequence** node (which lets you add extra outputs) or chain the actions one after another.
  </Accordion>

  <Accordion title="middleman — pass-through nodes">
    Nodes marked as pass-through (Tag User, Set Merchant, Set Variable, Has Tag, Wait Seconds, Show/Hide Element, the video checks, Sequence, and the generic conditions) are transparent for `only_on` resolution. Inserting one in the middle of a chain does not break a downstream node's parent requirement.
  </Accordion>
</AccordionGroup>

<Warning>
  **Server nodes cannot follow browser nodes on the same path.** A server-side node may be followed by a browser node (`script_rule` → `client_script` works), but not the other way round (`exit_intent` → `script_rule` does not work). Once a path reaches the browser it stays in the browser.
</Warning>

<Note>
  **Anything with a script becomes a Script Rule at runtime.** Before dispatching a node, the renderer checks for `data.script_rule` and, if present, treats the node as a `script_rule` regardless of its declared type. That is how **Query Parameter Condition**, **Is From Country** and every other generated condition actually execute — they are Script Rules with a pre-written script and a friendly form.
</Note>

***

## Node catalogue

| Node | Type | In / Out | Runs on |
| - | - | - | - |
| Loaded (entry) | `entry` | 0 / 1 | Server + Browser |
| Router | `router` | 1 / 1 | Server |
| Sequence | `sequence` | 1 / 2+ | Server + Browser |
| Stop Next Events Execution | `stop_execution` | 1 / 0 | Server + Browser |
| Script Rule | `script_rule` | 1 / 2 | Server |
| Query Parameter Condition | `query_param_condition` | 1 / 2 | Server |
| Is Customer | `is_customer` | 1 / 2 | Server |
| Has Purchased Any Upsell | `accepted_upsells` | 1 / 2 | Server |
| Referred By Affiliate | `referred_by_affiliate` | 1 / 2 | Server |
| Is From Country | `is_from_country` | 1 / 2 | Server |
| Is From State | `is_from_state` | 1 / 2 | Server |
| Is From EU | `is_from_eu` | 1 / 2 | Server |
| Is From Timezone | `is_from_timezone` | 1 / 2 | Server |
| Is Using VPN/Proxy | `is_using_vpn` | 1 / 2 | Server |
| Is Whitelisted? | `is_whitelisted` | 1 / 2 | Server + Browser |
| Has Tag | `has_tag` | 1 / 2 | Server + Browser |
| Cloaking.house | `cloaking_house` | 1 / 2 | Server + Browser |
| Product Check | `product_check` | 1 / 2 | Not declared |
| Product Check: Match Product | `product_check_product` | 1 / 1 | Not declared |
| Product Check: Match All | `product_check_all` | 1 / 1 | Not declared |
| Component Split Test | `component_split_test` | 1 / 2–5 | Server |
| Split Test | `split_test` | 1 / 2–5 | Server + Browser |
| Traffic Distribution | `split_test_weight` | 1 / 1 | Server + Browser |
| Component | `component_split_test_component` | 1 / 0 | Server |
| Dynamic Content | `dynamic_container` | 1 / 1 | Server |
| Load Another Page | `page_variant` | 1 / 1 | Server |
| Redirect to Page | `page` | 1 / 0 | Server + Browser |
| Redirect to URL | `url_redirect` | 1 / 0 | Server + Browser |
| Set Merchant | `set_merchant` | 1 / 1 | Server + Browser |
| Clear Merchant | `clear_merchant` | 1 / 1 | Server + Browser |
| Set Checkout Page | `set_checkout_page` | 1 / 1 | Server |
| Set Checkout Bumps | `set_checkout_bumps` | 1 / 1 | Server |
| Set Variable | `set_variable` | 1 / 1 | Server + Browser |
| Tag User | `add_tag` | 1 / 1 | Server + Browser |
| Whitelist visitor | `mark_whitelisted` | 1 / 1 | Server + Browser |
| Mark visitor as NOT whitelisted | `mark_not_whitelisted` | 1 / 1 | Server + Browser |
| Block Request | `block_request` | 1 / 0 | Server |
| Ban Visitor by IP | `ban_ip` | 1 / 0 | Server |
| Unban Visitor by IP | `unban_ip` | 1 / 0 | Server |
| Execute Automation on Customer | `execute_automation` | 1 / 1 | Not declared |
| On Exit Intent | `exit_intent` | 1 / 1 | Browser |
| On Exited Page | `on_exited_page` | 1 / 1 | Server |
| On Form Success | `on-form-success` | 1 / 1 | Browser |
| On Add To Cart | `on-add-to-cart` | 1 / 1 | Browser |
| CTA: On Shown | `on_cta` | 1 / 1 | Browser |
| When scrolled to | `when_scrolled_to` | 1 / 1 | Browser |
| Scroll Check | `scroll_check` | 1 / 2 | Browser |
| Element In View | `element_in_view` | 1 / 2 | Browser |
| If Showed CTA | `showed_cta` | 1 / 2 | Browser |
| If Added To Cart | `added_to_cart` | 1 / 2 | Browser |
| Video: Is muted | `video_is_muted` | 1 / 2 | Browser |
| Video: On Pause | `video_pause` | 1 / 1 | Browser |
| Video: On Goal Reached | `video_watched_seconds` | 1 / 1 | Browser |
| Video: Progress Check | `video_progress_check` | 1 / 2 | Browser |
| Show Video CTA | `show_video_cta` | 1 / 1 | Browser |
| Hide Video CTA | `hide_video_cta` | 1 / 1 | Browser |
| Show Element | `show_element` | 1 / 1 | Browser |
| Hide Element | `hide_element` | 1 / 1 | Browser |
| Wait Seconds | `wait_seconds` | 1 / 1 | Browser |
| Show Popup | `exit_popup` | 1 / 0 | Browser |
| Execute Javascript on Client | `client_script` | 1 / 1 | Browser |

<Note>
  **"Not declared"** means the node definition in the builder does not state where it runs. In practice the renderer handles all three on the **server**: `product_check` inspects the purchased products, and `execute_automation` mints a token server-side and then hands the actual call to the browser. Treat them as server nodes when ordering a path, and confirm with the [Debug Window](/debugging/debug-window) if a mixed path behaves unexpectedly.
</Note>

***

## Entry & flow control

### Loaded (entry point)

**Type** `entry` · **0 in / 1 out** · Server + Browser

The start of a flow. `data.value` holds the ID of the page the flow belongs to.

A page can have **more than one entry node**. Each one is a separate **View** in the left rail of the builder, and their order is stored in `entry_views_order`.

<Note>
  Views are an **organisational device for the canvas only**. At render time every entry node's children are collected and run — the renderer does not pick one entry and ignore the rest, and it does not read `entry_views_order`. If you need only one branch to run, put the choice behind a condition, not behind separate views.
</Note>

**Fields**

| Field | Description |
| - | - |
| `value` | Page ID this entry belongs to. Set automatically. |
| `view_name` | Name shown in the Views rail. Set with the pencil icon; unnamed views display as `View <id>`. |
| `view_canvas_x` / `view_canvas_y` | Saved camera position for that view. Set automatically. |

### Router

**Type** `router` · **1 in / 1 out** · pass-through

A junction node used to tidy up the canvas. It carries a short `code` that can be used to build a node-specific URL.

**Fields:** `code` (generated).

### Sequence

**Type** `sequence` · **1 in / 2+ out** · Server + Browser · pass-through

Runs the connected branches one after another. Because every other node is limited to one connection per output, Sequence is how you fan out several actions from a single branch — click **Add Sequence Output** on the node to add more output pins.

**Fields:** none.

See [Sequence Nodes](/funnels/sequence-nodes).

### Stop Next Events Execution

**Type** `stop_execution` · **1 in / 0 out** · Server + Browser

Ends processing for this path. Nothing after it runs — and it also **discards the browser-side event queue for this request**, so triggers that would have shipped to the page are dropped too.

**Fields:** none.

***

## Conditions (server)

All condition nodes send the flow to **Output 1** when true and **Output 2** when false.

### Script Rule

**Type** `script_rule` · **1 in / 2 out** · Server · `only_on: entry, script_rule`

Custom JavaScript that returns a boolean. This is the most flexible condition and the parent type that most generated conditions inherit from.

**Fields**

| Field | Description |
| - | - |
| `script_rule` | The script body. Write only the body — no `function` wrapper — ending in a `return` of a boolean. |
| `script_prompt` | The plain-language description used when the script was generated with AI. Optional. |
| `intelligence_session_id` | AI chat session that produced the script. Set automatically. |

<Note>
  `only_on` restricts Script Rule to sit under an entry node or another Script Rule — but because every generated condition below carries `base_type: script_rule`, you can also chain a Script Rule under **Is From Country**, **Query Parameter Condition**, and the rest.
</Note>

Full variable reference: [Script Rule](/funnels/script-rule).

### Query Parameter Condition

**Type** `query_param_condition` · **1 in / 2 out** · Server · pass-through

A structured builder for URL parameter checks. The node **compiles your conditions into a `script_rule`** and stores both — and the renderer executes it as a Script Rule against the `query` object.

**Fields**

| Field | Description |
| - | - |
| `conditions` | Array of `{ param, operator, value, logicalOperator }`. |
| `script_rule` | The compiled script — **this is what actually executes**. The builder regenerates it every time you edit `conditions`; nothing on the server does. |

<Warning>
  Writing the graph through the API (`POST /api/brands/{brand}/pages/{page}/events`) you must send **both** fields, kept in sync. `conditions` alone is inert: the compile step lives in the builder UI, so a node saved with conditions but no `script_rule` has nothing to run and its condition never passes. Only edit `script_rule` by hand when you are writing the graph directly — in the builder, edit `conditions` and let it recompile.
</Warning>

**Operators**

| Operator | Generated comparison |
| - | - |
| `is` | `query.<param> == '<value>'` |
| `is_not` | `query.<param> != '<value>'` |
| `contains` | `query.<param>.includes('<value>')` |
| `does_not_contain` | `!query.<param>.includes('<value>')` |
| `starts_with` | `query.<param>.startsWith('<value>')` |
| `ends_with` | `query.<param>.endsWith('<value>')` |
| `is_empty` | `!query.<param> \|\| query.<param> == ''` — true when the parameter is missing **or** blank |
| `is_not_empty` | `query.<param> && query.<param> != ''` |

`logicalOperator` is `&&` (AND) or `||` (OR) and joins a condition to the **next** one in the list. The legacy values `and` / `or` are normalised to `&&` / `||` on load.

**Outputs** — `output_1` runs when the compiled condition is **true**, `output_2` when it is **false**. Either may be left unconnected; an empty branch simply does nothing.

Say the condition positively and hang the work off the branch you want, rather than inverting the operator. "Serve the white page unless the URL carries `?test=1`" is one condition — `is` / `test` / `1` — with the white-page node on **`output_2`**, the false branch.

<Warning>
  `is_empty` is not the way to express "missing `test=1`". It only asks whether the parameter is **present**, ignoring its value, so `?test=2` counts as *not* empty and the branch never fires. When the user means "anything other than `test=1`", compare the value: `is` on `output_2`, or equivalently `is_not` on `output_1`.
</Warning>

<Warning>
  There are no numeric operators. `greater than` / `less than` do not exist on this node — use a **Script Rule** for numeric comparisons.
</Warning>

See [Query Parameter Conditions](/funnels/query-parameters).

### Generated conditions

These nodes are Script Rules with a fixed script and a friendly form. They all have **1 in / 2 out**, run on the **server**, and are pass-through.

| Node | Type | Fields | Generated script |
| - | - | - | - |
| Is Customer | `is_customer` | — | `return is_customer;` |
| Has Purchased Any Upsell | `accepted_upsells` | — | `return customer && customer.accepted_upsells;` |
| Referred By Affiliate | `referred_by_affiliate` | `affiliate_ids` (array of affiliate merchant account IDs) | `return [...].includes(session.aff_id);` |
| Is From Country | `is_from_country` | `countries` (array of ISO country codes) | `return [...].includes(ip_whois.country_code);` |
| Is From State | `is_from_state` | `states` (array of US state codes) | `return ip_whois.country_code == "US" && [...].includes(ip_whois.state);` |
| Is From EU | `is_from_eu` | — | `return ip_whois.is_eu;` |
| Is From Timezone | `is_from_timezone` | `timezones` (array of IANA IDs) | `return [...].includes(ip_whois.timezone.id);` |
| Is Using VPN/Proxy | `is_using_vpn` | — | `return ip_whois.security.vpn \|\| ip_whois.security.proxy \|\| ip_whois.security.tor \|\| ip_whois.security.anonymous;` |

Each of these also stores the compiled script under `script_rule`, and that is what the renderer runs.

<Warning>
  The generated scripts read `ip_whois.country_code`, `ip_whois.state`, `ip_whois.is_eu`, `ip_whois.timezone.id` and `ip_whois.security.*`. If you write your own Script Rule, use those same paths — see [Script Rule → `ip_whois`](/funnels/script-rule#ip_whois).
</Warning>

<Tip>
  Prefer these over a hand-written Script Rule — they are cheaper to read and they document intent. Reach for Script Rule only when you need logic these cannot express.
</Tip>

**Timezone options in the picker:** `America/New_York`, `America/Chicago`, `America/Denver`, `America/Los_Angeles`, `Europe/London`, `Europe/Paris`, `Asia/Tokyo`, `Australia/Sydney`.

### Is Whitelisted?

**Type** `is_whitelisted` · **1 in / 2 out** · Server + Browser · pass-through

Checks whether the visitor currently counts as whitelisted.

**Fields:** none.

### Has Tag

**Type** `has_tag` · **1 in / 2 out** · Server + Browser · pass-through

Checks for a tag set by **Tag User**, `ef.addTag()`, or [`addTag()` in a backend script](/backend-scripts/tags).

**Fields:** `value` — tag name.

### Cloaking.house

**Type** `cloaking_house` · **1 in / 2 out** · Server + Browser · pass-through

Routes based on a Cloaking.house verdict.

**Fields:** `value`, `label`.

### Product Check

**Type** `product_check` · **1 in / 2 out**

Branches on which product was purchased. It is a parent node: each output must carry one child.

* **Product Check: Match Product** (`product_check_product`, `only_on: product_check`) — `value` = product code to match.
* **Product Check: Match All** (`product_check_all`, `only_on: product_check`) — catch-all for everything not matched.

***

## Conditions (browser)

### Scroll Check

**Type** `scroll_check` · **1 in / 2 out** · Browser · pass-through

Has the visitor already scrolled past a point? Desktop and mobile thresholds are configured separately.

**Fields:** `value` (desktop pixels from top), `percent` (desktop % of page), `value_mobile`, `percent_mobile`.

### Element In View

**Type** `element_in_view` · **1 in / 2 out** · Browser · pass-through

Is an element currently visible in the viewport?

**Fields:** `value` (CSS selector), `min_percent_visible` (0–100).

### If Showed CTA

**Type** `showed_cta` · **1 in / 2 out** · Browser · pass-through

Has the video CTA already been shown?

**Fields:** none.

### If Added To Cart

**Type** `added_to_cart` · **1 in / 2 out** · Browser · pass-through · requires `products.view`

**Fields:** `value` — product code.

### Video: Is muted

**Type** `video_is_muted` · **1 in / 2 out** · Browser · pass-through · `only_on: exit_intent`

Checks whether the main video is muted. It can only be attached below an **On Exit Intent** node.

**Fields:** none.

### Video: Progress Check

**Type** `video_progress_check` · **1 in / 2 out** · Browser · pass-through

Has the video reached a position?

**Fields:** `value` (seconds), `percent` (% of duration).

***

## Triggers (browser)

Triggers wait for something to happen, then continue down their single output.

| Node | Type | Fields | Notes |
| - | - | - | - |
| On Exit Intent | `exit_intent` | — | `only_on: entry, script_rule` |
| On Form Success | `on-form-success` | `form` (form ID) | |
| On Add To Cart | `on-add-to-cart` | — | requires `products.view` |
| CTA: On Shown | `on_cta` | — | |
| When scrolled to | `when_scrolled_to` | `value` (pixels from top), `percent` (% of page) | Either threshold can fire it |
| Video: On Pause | `video_pause` | — | pass-through |
| Video: On Goal Reached | `video_watched_seconds` | `value` (seconds watched), `percent` (% watched) | pass-through |

### On Exited Page

**Type** `on_exited_page` · **1 in / 1 out** · **Server**

Despite the name, this node is declared as a server-side node in the builder rather than a browser trigger.

**Fields:** none.

<Warning>
  We could not find a handler for `on_exited_page` on either the server or the browser side of the renderer, and it is not in the list of trigger nodes that get promoted to their own root event. It may be a no-op in its current form. Verify with the [Debug Window](/debugging/debug-window) before building on it.
</Warning>

***

## Content & routing actions

### Dynamic Content

**Type** `dynamic_container` · **1 in / 1 out** · Server · requires `pages.create` or `pages.update`

Replaces the contents of a `<dynamic-container>` on the page with a saved component.

**Fields**

| Field | Required | Description |
| - | - | - |
| `container` | Yes | The `id` of the `<dynamic-container>` to fill. The node warns *"Container is required"* until set. |
| `component` | Yes | The **code** of the component to render. The node warns *"Component is required"* until set. |

The container dropdown is populated from `GET /api/brands/{brand}/pages/{page}/component-type/dynamic-container`; the component dropdown from `GET /api/brands/{brand}/components/all?short=true`.

Full guide: [Dynamic Content](/funnels/dynamic-content).

### Load Another Page

**Type** `page_variant` · **1 in / 1 out** · Server · requires `pages.create` or `pages.update`

Renders a **different page's content at the current URL**. No redirect, no URL change.

<Note>
  Three nodes read alike and are not interchangeable:

  | What you want | Node | Address bar |
  | - | - | - |
  | Show another page's content where the visitor already is | `page_variant` | unchanged |
  | Send the visitor to another page in this brand | `page` | changes |
  | Send the visitor to any other address | `url_redirect` | changes |

  "Load", "show", and "serve" mean `page_variant`. "Redirect", "send", and "go to" mean one of the redirect nodes. The distinction matters most when a condition guards a safe or white page: a redirect moves the visitor to a different URL, which is not the same thing as serving different content at the one they asked for — only `page_variant` does that. `page_variant` also keeps an output, so the graph can carry on after it; both redirect nodes are terminal.
</Note>

**Fields**

| Field | Description |
| - | - |
| `value` | ID of the page (or page variant) to load. |
| `slug` | Slug of that page. Set automatically. |
| `load_page_events` | **Load & Override Page Events.** Off by default: the variant inherits the primary page's events. Turn on to give the variant its own event graph — the renderer then reloads the events for the loaded page and re-runs the event pass (capped at 3 reloads, so avoid chains of variants that each override events). |

The node is skipped in preview mode so you can inspect the original page.

See [Page Variants](/pages/page-variants).

### Redirect to Page

**Type** `page` · **1 in / 0 out** · Server + Browser

Sends the visitor to another page in the brand. The path ends here.

**Fields:** `value` (page ID), `slug`, `code`.

### Redirect to URL

**Type** `url_redirect` · **1 in / 0 out** · Server + Browser

Sends the visitor to any URL. The path ends here.

**Fields:** `value` (target URL), `keep_query_params` (boolean — carry the current query string over; on by default, set it to `false` to drop it).

The target URL supports two placeholder families, in both brace and percent form: `{click_id}` and `{query.<param>}`. A redirect back to the same host as the current request is suppressed so a rule cannot put the page into a loop.

### Show Popup

**Type** `exit_popup` · **1 in / 0 out** · Browser · requires `exitpopups.view`

**Fields:** `value` — popup ID.

See [Exit Popups](/funnels/exit-popups).

### Show Element / Hide Element

**Types** `show_element` / `hide_element` · **1 in / 1 out** · Browser · pass-through

**Fields:** `value` — CSS selector.

### Show Video CTA / Hide Video CTA

**Types** `show_video_cta` / `hide_video_cta` · **1 in / 1 out** · Browser · pass-through

`show_video_cta` takes `scroll_to` (boolean) — scroll the page to the CTA when it appears. `hide_video_cta` has no fields.

### Wait Seconds

**Type** `wait_seconds` · **1 in / 1 out** · Browser · pass-through

**Fields:** `value` — seconds to pause before continuing.

### Execute Javascript on Client

**Type** `client_script` · **1 in / 1 out** · Browser

Runs a snippet in the page.

**Fields:** `client_script` — the JavaScript source.

<Warning>
  The flow does **not** advance automatically after a client script. Call `ef.nextNode()` when you want the next node to run. See [Window API](/funnels/window-api).
</Warning>

***

## Session, commerce & security actions

### Tag User

**Type** `add_tag` · **1 in / 1 out** · Server + Browser · pass-through

**Fields:** `value` (tag name), `expiration_minutes` (omit or `0` for a session cookie; a positive number expires the tag after that many minutes — `10080` = 7 days).

<Warning>
  A backend script can read and write the same tags with [`hasTag()` / `addTag()` / `removeTag()`](/backend-scripts/tags), which handle the naming split below for you.

  **Server and browser write the tag cookie under different names.** When the node runs on the server the cookie is named exactly `value`; when it runs in the browser it is named `tag_<value>`. **Has Tag** on the server reads the bare name, while the `tags` array exposed to Script Rules is built from `tag_`-prefixed cookies only. Keep a tag's set/read pair on the same side of the fence, or set tags from the browser with `ef.addTag()` and read them with `tags.includes(...)`.
</Warning>

### Whitelist visitor

**Type** `mark_whitelisted` · **1 in / 1 out** · Server + Browser · pass-through

**Fields:** `value` — expiration in minutes. **`0` whitelists the visitor permanently.**

Both nodes write an encrypted, `httpOnly` cookie named `whtst`. `Whitelist visitor` with `value: 0` sets it for ten years; `Mark visitor as NOT whitelisted` sets a 7-day negative cookie. Within the same request the change takes effect immediately, so **Is Whitelisted?** placed after either node sees the new value.

### Mark visitor as NOT whitelisted

**Type** `mark_not_whitelisted` · **1 in / 1 out** · Server + Browser · pass-through

**Fields:** none.

Both feed the Whitelisted / Non-Whitelisted containers — see [Content Visibility Control](/pages/visitor-based-content).

### Set Merchant

**Type** `set_merchant` · **1 in / 1 out** · Server + Browser · pass-through · requires `merchants.view`

**Fields:** `value` (merchant ID), plus `merchant_gateway` and `merchant_account_id`, which are filled in automatically from the selected merchant.

<Note>
  **Set Merchant, Clear Merchant and Set Checkout Page are ignored once the visitor has purchased in this session.** The renderer refuses to move a buyer onto a different processor or checkout mid-flow.
</Note>

### Clear Merchant

**Type** `clear_merchant` · **1 in / 1 out** · Server + Browser · pass-through · requires `merchants.view`

Resets the merchant back to the domain default. **Fields:** none.

### Set Checkout Page

**Type** `set_checkout_page` · **1 in / 1 out** · Server · pass-through

Overrides which checkout page this session uses.

**Fields:** `value` (page ID), `slug`.

See [Checkout redirect behavior](/funnels/checkout-redirect-behavior).

### Set Checkout Bumps

**Type** `set_checkout_bumps` · **1 in / 1 out** · Server · pass-through

**Fields:** `bumps` — array of bump objects (`title`, `description`, `price`, `added_message`, product code).

<Note>
  This node is only offered in **Add Node** when the page is flagged as a checkout page.
</Note>

### Set Variable

**Type** `set_variable` · **1 in / 1 out** · Server + Browser · pass-through

Sets page variables for the rest of the render.

**Fields:** `variables` — an object of key/value pairs.

See [Page Variables](/pages/page-variables).

### Execute Automation on Customer

**Type** `execute_automation` · **1 in / 1 out** · requires `automations.view`

**Fields:** `automation_id`, `delay` (seconds, optional).

### Block Request

**Type** `block_request` · **1 in / 0 out** · Server · pass-through

**Fields:** `value` — the message shown to the blocked visitor.

<Warning>
  Attach **Block Request** to the specific output of a condition. If you drop it directly under the entry node it blocks **every** request.
</Warning>

### Ban Visitor by IP / Unban Visitor by IP

**Types** `ban_ip` / `unban_ip` · **1 in / 0 out** · Server · pass-through

**Fields:** none.

<Warning>
  These two nodes are offered in the builder but **the page renderer has no handler for them** — a path that reaches `ban_ip` or `unban_ip` simply stops. Do not rely on them for access control; use **Block Request** behind a condition instead.
</Warning>

***

## Split testing

These nodes are covered end to end in [Split Testing](/funnels/split-testing). Summary:

### Component Split Test

**Type** `component_split_test` · **1 in / 2–5 out** · Server · requires `split_tests.create` or `split_tests.update`

Splits traffic between components rendered into a `<split-test>` container on this page.

**Fields**

| Field | Description |
| - | - |
| `container` | `id` of the `<split-test>` container on the page. Required. |
| `container_name` | Cached display name of that container. Set automatically. |
| `value` | Number of variants: `2`, `3`, `4` or `5`. Changing it adds or removes output pins **and their Traffic Distribution nodes**. |
| `name` | Test name, shown in split-test reporting. |
| `enforce_exact_split` | `1` / `0`, set by the **Enforce Exact Split** checkbox. See the note below. |
| `split_test_id` | ID of the split test record. Assigned when you save — do not set by hand. |
| `winner_node_code` | `node_code` of the Traffic Distribution node marked as winner. When set, that variant is served to everyone and the weights are ignored. |

<Note>
  **On `enforce_exact_split`:** the flag is stored on the node and carried into the published flow, but the current page renderer does not read it. Component split tests already allocate traffic **exactly** — a shared counter (Redis-backed, so it holds across workers) drives a smooth weighted rotation rather than a per-visitor dice roll. Leaving the box unchecked does not make allocation random.
</Note>

<Warning>
  A **Component Split Test** node **ends its branch**. It performs the container swap and stops — anything wired after it (rather than under a Traffic Distribution node) will not run.
</Warning>

Advanced statistics saved through the node's **Advanced Settings** modal (and to `PUT /api/brands/{brand}/split-tests/{id}` once `split_test_id` exists): `duration`, `sample_size_limit`, `min_sample_size_per_variant`, `significance_level`, `statistical_power`, `minimum_detectable_effect`, `multiple_testing_correction`, `early_stopping_enabled`, `statistical_method`, `sequential_testing_interval`, `primary_metric`, `winner_selection_criteria`, `practical_significance_threshold`, `require_practical_significance`, `check_guardrail_metrics`, `guardrail_metrics`, `goals`, `enable_automated_winner_selection`, `automated_decision_threshold`, `auto_select_winner`, `winner_selection_confidence`.

### Split Test

**Type** `split_test` · **1 in / 2–5 out** · Server + Browser · requires `split_tests.create` or `split_tests.update`

The non-component split test: splits traffic between whole branches of the flow rather than between components in one container. Each output takes one **Traffic Distribution** node, and whatever hangs below that weight is the variant — commonly a **Load Another Page**.

**Fields:** `value` (2–5), `name`, `enforce_exact_split` (see the note above), `split_test_id`, `winner_node_code`.

<Note>
  Unlike Component Split Test, `split_test` can run on either side. On the server the branch is chosen from a shared exact-rotation counter; if the test is handed to the browser instead, selection is a weighted random draw stored in the `st_res_<split_test_id>` cookie.
</Note>

### Traffic Distribution

**Type** `split_test_weight` · **1 in / 1 out** · Server + Browser · `only_on: component_split_test, split_test`

One per variant. Created automatically when you change the parent's variant count.

**Fields**

| Field | Description |
| - | - |
| `value` | Percentage of traffic, `0`–`100`. Editing one weight redistributes the remainder evenly across its siblings. |
| `name` | Variant name, used in reporting. |
| `is_winner` | `1` on the winning variant, `0` on the others, absent while the test runs. Marking a winner writes that variant's `node_code` to the parent's `winner_node_code`. |
| `node_code` | Stable short code. This is the value used as `filter[node_code]` in analytics. |

### Component

**Type** `component_split_test_component` · **1 in / 0 out** · Server · `only_on: split_test_weight` · requires `pagecomponents.view`

The component rendered for one variant.

**Fields:** `component` (component code), `baseline` (boolean — mark the control).

***

## Related

<CardGroup>
  <Card title="Page Events" href="/funnels/page-events" />

  <Card title="Split Testing" href="/funnels/split-testing" />

  <Card title="Dynamic Content" href="/funnels/dynamic-content" />

  <Card title="Script Rule" href="/funnels/script-rule" />

  <Card title="Query Parameters" href="/funnels/query-parameters" />

  <Card title="Sequence Nodes" href="/funnels/sequence-nodes" />

  <Card title="Window API" href="/funnels/window-api" />

  <Card title="Debug Window" href="/debugging/debug-window" />
</CardGroup>


# Query Parameter Conditions
Source: https://docs.elasticfunnels.io/funnels/query-parameters

Use URL parameters to control visitor behavior and content display

Query Parameter Conditions allow you to create dynamic experiences based on URL parameters. This is essential for affiliate tracking, content visibility control, and personalized visitor experiences.

## Understanding Query Parameters

Query parameters are the part of a URL that comes after the `?` symbol:

* **Base URL**: `https://yoursite.com/page`
* **With parameters**: `https://yoursite.com/page?vtID=k&source=facebook`

In this example:

* `vtID` is a parameter with value `k`
* `source` is a parameter with value `facebook`

## Query Parameter Condition Node

The Query Parameter Condition node checks if URL parameters exist or have specific values. It runs on the **server**, before the page is sent, and it has two outputs: **Output 1 when the condition is true**, Output 2 when it is false.

### Basic Setup

1. Go to **Page Events** for your page
2. Click **"Add Node"**
3. Select **"Query Parameter Condition"**
4. Add one or more conditions — each is a parameter name, an operator, a value, and how it joins the next one
5. Connect Output 1 and Output 2 to the appropriate nodes

### Available Operators

| Operator | Matches when |
| - | - |
| **is** | The parameter equals the value exactly |
| **is not** | The parameter does not equal the value |
| **contains** | The value appears anywhere in the parameter |
| **does not contain** | The value does not appear in the parameter |
| **starts with** | The parameter begins with the value |
| **ends with** | The parameter ends with the value |
| **is empty** | The parameter is **missing or blank** (no value field needed) |
| **is not empty** | The parameter is present and non-blank (no value field needed) |

<Warning>
  There are **no numeric operators** on this node — "greater than" and "less than" do not exist. All comparisons are string comparisons. For numeric logic use a [Script Rule](/funnels/script-rule): `return parseInt(query.qty) > 3;`
</Warning>

### Combining conditions

Add several conditions to one node and set each row's **logical operator** to **AND** or **OR**. The operator on a row joins it to the **next** row, and the conditions are evaluated left to right with JavaScript precedence — `A AND B OR C` is `(A AND B) OR C`. There is no grouping; for anything more nested, use a Script Rule.

<Note>
  Under the hood the node compiles your conditions into a Script Rule against the `query` object and stores it on the node. That is what actually runs, which is why the semantics match JavaScript exactly. Do not hand-edit the generated script — it is rewritten every time you change a condition.
</Note>

## Common Use Cases

### Content Whitelisting

Use parameters to control access to full content:

**Example**: `https://yoursite.com/page?vtID=k`

**Configuration**:

1. Go to **Page Events** for the specific page you want to configure
2. From the **"On Page Loaded"** node, drag a new **"Query Parameter Condition"** node
3. Configure: Parameter `vtID`, Operator `Equals`, Value `k`
4. From the **"Query Parameter Condition"** node, drag a **"Whitelist Visitor"** node

**Result**: Visitors with the correct parameter see full content

### Affiliate Tracking

Track different affiliate sources:

**Example**: `https://yoursite.com/page?affID=100`

**Configuration**:

* Parameter: `affID`
* Operator: `Equals`
* Value: `100`
* Action: `Dynamic Container` (show affiliate-specific content)

### Campaign Tracking

Show different content based on campaign:

**Example**: `https://yoursite.com/page?campaign=summer2024`

**Configuration**:

* Parameter: `campaign`
* Operator: `Equals`
* Value: `summer2024`
* Action: `Dynamic Container` (show summer promotion)

### Geographic Targeting

Redirect based on location parameter:

**Example**: `https://yoursite.com/page?country=US`

**Configuration**:

* Parameter: `country`
* Operator: `Equals`
* Value: `US`
* Action: `Load Page` (US-specific page)

## Advanced Parameter Logic

### Multiple Conditions

You can check multiple parameters in sequence:

1. **First condition**: Check if `vtID` is not empty
2. **Second condition**: Check if `source` equals `facebook`
3. **Action**: Show Facebook-specific whitelisted content

### Conditional Branching

Use different actions based on parameter values:

**Setup**:

* Parameter: `traffic_source`
* **If equals "google"** → Show Google-optimized content
* **If equals "facebook"** → Show Facebook-optimized content
* **If empty** → Show default content

### Parameter Validation

Ensure parameters meet specific criteria:

**Example**: Only whitelist if affiliate ID is valid

* Parameter: `affID`
* Operator: `Greater Than`
* Value: `0`
* Action: `Whitelist Visitor`

## Integration with Other Features

### Whitelisting System

Query parameters are the primary method for visitor whitelisting:

**Common patterns**:

* `vtID=k` for general whitelisting
* `access=premium` for premium content
* `preview=true` for preview mode

### Split Testing

Use parameters to control which visitors see which tests:

**Example**: `https://yoursite.com/page?test=variant_a`

* Show specific split test variant based on parameter
* Useful for controlled testing or affiliate-specific variants

### Dynamic Content

Parameters can trigger dynamic content changes:

**Example**: `https://yoursite.com/page?price=discounted`

* Show special pricing based on parameter
* Useful for limited-time offers or special promotions

## Best Practices

### Parameter Naming

* **Use clear names** - `vtID`, `affID`, `campaign` are descriptive
* **Be consistent** - Use the same parameter names across all pages
* **Avoid conflicts** - Don't use parameter names that conflict with system parameters

### Security Considerations

* **Don't rely on parameters alone** for security
* **Validate parameter values** to prevent injection attacks
* **Use HTTPS** when passing sensitive information
* **Consider parameter encryption** for highly sensitive data

### URL Management

* **Keep URLs clean** - Use only necessary parameters
* **Document parameter usage** - Maintain a list of all parameters and their purposes
* **Test parameter combinations** - Ensure multiple parameters work together

## Common Parameter Patterns

### Affiliate Tracking

Standard parameters for affiliate management:

* `affID` or `aff` - Affiliate identifier
* `subID` - Sub-affiliate or campaign identifier
* `source` - Traffic source (google, facebook, etc.)
* `medium` - Traffic medium (cpc, social, email, etc.)

### Content Control

Parameters for content management:

* `vtID` - Visitor type identifier for whitelisting
* `access` - Access level (free, premium, vip)
* `preview` - Preview mode for testing
* `version` - Content version or variant

### Campaign Tracking

Parameters for campaign management:

* `campaign` - Campaign name or identifier
* `utm_source` - UTM source tracking
* `utm_medium` - UTM medium tracking
* `utm_campaign` - UTM campaign tracking

## Troubleshooting

### Common Issues

* **Parameter not recognized** - Check spelling and case sensitivity
* **Condition not triggering** - Verify operator and value match exactly
* **Multiple parameters conflicting** - Check the order of conditions
* **URL encoding issues** - Ensure special characters are properly encoded

### Testing Parameters

1. **Manual testing** - Add parameters to URLs and test functionality
2. **Browser tools** - Use developer tools to inspect parameter values
3. **Incognito mode** - Test without cached data
4. **Different browsers** - Ensure cross-browser compatibility

### Debugging Tips

* **Check parameter spelling** - Parameters are case-sensitive
* **Verify operator logic** - Ensure you're using the correct operator
* **Test empty states** - Check what happens when parameters are missing
* **Monitor page events** - Use debugging tools to track node execution

## Multi-Parameter Logic

### Dynamic Parameter Generation

Generate parameters dynamically:

* **JavaScript generation** - Create parameters based on user behavior
* **Server-side generation** - Add parameters based on server logic
* **Third-party integration** - Parameters from external systems

### Parameter Persistence

Maintain parameters across page navigation:

* **Session storage** - Store parameters for the session
* **Local storage** - Store parameters persistently
* **URL rewriting** - Automatically add parameters to all links

### API Integration

Use parameters for API calls:

* **Pass parameters to external APIs** - Forward tracking data
* **Receive parameters from APIs** - Get data from external systems
* **Webhook integration** - Send parameter data to webhooks

<Note>
  Keep query parameters focused. Too many parameters make URLs harder to read, test, and share.
</Note>


# Script Rule
Source: https://docs.elasticfunnels.io/funnels/script-rule

Advanced JavaScript-based conditional logic with access to visitor data, device info, geolocation, and more

Script Rule is a Page Events node for custom JavaScript logic. Use it when query parameter rules are not enough and you need to route visitors based on session, device, traffic, or purchase data.

## When to Use Script Rule

Script Rules are ideal when you need:

* **Complex conditional logic** - Multiple conditions combined with AND/OR operators
* **Geolocation-based routing** - Direct visitors based on country, region, ISP, or connection type
* **Behavior-based decisions** - Route based on visit frequency, time between visits, or browsing patterns
* **Customer segmentation** - Different flows for existing customers vs new visitors
* **Anti-fraud protection** - Detect suspicious patterns like rapid page visits or VPN usage
* **Device/Platform targeting** - Advanced device detection beyond simple mobile/tablet/desktop
* **Tag-based routing** - Check for multiple tags with complex logic
* **Click attribution** - Route based on traffic source, click age, or IP matching

<Note>
  Script Rules execute on the server before the page loads, making them perfect for security-sensitive decisions that shouldn't be exposed to the browser.
</Note>

## How Script Rules Work

1. **Server-Side Execution**: Script Rules run on the server before the page loads
2. **Return Boolean**: Your script must return `true` or `false`
3. **Flow Control**:
   * `true` → **Output 1**, the Yes path
   * `false` → **Output 2**, the No path
4. **Available Data**: You have access to pre-loaded visitor data (see below)

<Note>
  **The purpose-built conditions are Script Rules too.** *Is From Country*, *Is From State*, *Is From EU*, *Is From Timezone*, *Is Using VPN/Proxy*, *Is Customer*, *Has Purchased Any Upsell*, *Referred By Affiliate* and *Query Parameter Condition* all generate a script and store it on the node — the renderer treats any node carrying a script as a Script Rule. Prefer them when they fit: they are readable, validated, and use the same variables documented here. Reach for a raw Script Rule only for logic they cannot express.
</Note>

## Available Data Variables

### Core Variables

#### `is_whitelisted`

**Type:** Boolean\
**Description:** Whether the visitor is currently whitelisted

```javascript theme={null}
// Route whitelisted visitors differently
return is_whitelisted === true;
```

#### `whitelist_source`

**Type:** String | Null\
**Values:** `'same_request'`, `'same_request_blocked'`, `'cookie'`, `'cookie_blocked'`, `'expired_cookie'`, `'domain_all_whitelisted'`, `null`\
**Description:** How the whitelist status was determined. `same_request` means a **Whitelist visitor** node ran earlier in this same request, before this Script Rule.

```javascript theme={null}
// Only allow domain-level whitelist
return whitelist_source === 'domain_all_whitelisted';
```

#### `query`

**Type:** Object\
**Description:** All URL query parameters as key-value pairs

```javascript theme={null}
// Check multiple query parameters
return query.source === 'facebook' && query.campaign === 'spring2024';

// Check if parameter exists
return query.hasOwnProperty('affiliate_id');
```

#### `ip_address`

**Type:** String\
**Description:** Visitor's IPv4 address

```javascript theme={null}
// Block specific IP range
return !ip_address.startsWith('192.168.');
```

#### `ip_address6`

**Type:** String\
**Description:** Visitor's IPv6 address (if available)

```javascript theme={null}
// Allow only IPv6 traffic
return ip_address6 !== '' && ip_address6 !== null;
```

#### `referer` / `referrer`

**Type:** String\
**Description:** HTTP referrer URL (both spellings available)

```javascript theme={null}
// Check traffic source
return referer.includes('google.com') || referer.includes('facebook.com');

// Direct traffic only
return referer === '' || referer === null;
```

#### `merchant_code`

**Type:** String\
**Description:** Active payment processor code (e.g., 'buygoods', 'clickbank', 'digistore24')

```javascript theme={null}
// Route based on merchant
return merchant_code === 'buygoods';
```

***

### Device Information

#### `is_mobile`

**Type:** Boolean\
**Description:** Whether visitor is on a mobile device

```javascript theme={null}
// Mobile-only offers
return is_mobile === true;
```

#### `is_tablet`

**Type:** Boolean\
**Description:** Whether visitor is on a tablet device

```javascript theme={null}
// Exclude tablets from mobile offers
return is_mobile === true && is_tablet === false;
```

#### `device`

**Type:** Object\
**Description:** Detailed device information

**Available Properties:**

* `device.type` - Device type (e.g., 'smartphone', 'tablet', 'desktop')
* `device.brand` - Device brand (e.g., 'Apple', 'Samsung', 'Google')
* `device.model` - Device model
* `device.os` - Operating system
* `device.os_version` - OS version
* `device.browser` - Browser name
* `device.browser_version` - Browser version

```javascript theme={null}
// Target specific platforms
return device.os === 'iOS' && device.brand === 'Apple';

// Exclude old browsers
return device.browser !== 'Internet Explorer';

// Check OS version
return device.os === 'Android' && parseInt(device.os_version) >= 10;
```

**Page templates:** The same device and request fields (`is_mobile`, `is_tablet`, `device`, `query`, `is_customer`, etc.) are available in page content. Use `@if(request.is_mobile)` or `@if(is_mobile)` and `{{ request.* }}` — see [Page Variables → Request & device context](/pages/page-variables#request--device-context).

***

### Customer Data

#### `is_customer`

**Type:** Boolean\
**Description:** Whether visitor has made a purchase

```javascript theme={null}
// Existing customers only
return is_customer === true;

// New visitors only
return is_customer === false;
```

#### `is_test_customer`

**Type:** Boolean\
**Description:** Whether customer purchase was marked as test

```javascript theme={null}
// Exclude test purchases
return is_customer === true && is_test_customer === false;
```

#### `customer`

**Type:** Object\
**Description:** Customer information from last purchase

**Available Properties:**

* `customer.name` - Customer name
* `customer.email` - Customer email
* `customer.phone` - Customer phone
* `customer.country` - Customer country
* `customer.zip` - Postal code
* `customer.city` - City
* `customer.address` - Street address
* `customer.order_id` - Last order ID
* `customer.order_item` - Last purchased product code
* `customer.order_item_name` - Last purchased product name
* `customer.order_ids` - Array of all order IDs
* `customer.is_test` - Whether it's a test order

```javascript theme={null}
// Target customers from specific country
return is_customer && customer.country === 'US';

// Check if they bought specific product
return customer.order_item === 'product-123';

// Multiple purchases
return customer.order_ids && customer.order_ids.length > 1;
```

***

### Session & Tracking

#### `session`

**Type:** Object\
**Description:** A deliberately narrow slice of the visitor's session. **Only two keys are exposed:**

* `session.aff_id` — affiliate ID
* `session.aff_source` — affiliate source

```javascript theme={null}
// Specific affiliate only
return session.aff_id === 'affiliate-001';

// Any affiliate traffic
return session.aff_id !== null && session.aff_id !== '';
```

<Note>
  There is no `request`, `cookies` or `headers` object in a Script Rule. Header-derived facts are surfaced as `is_mobile`, `is_tablet`, `device` and `referer`; cookie-derived facts as `tags`, `is_whitelisted` and `is_customer`.
</Note>

#### `time` / `utc_timestamp`

**Type:** Number (Unix timestamp in milliseconds)\
**Description:** Current server time

```javascript theme={null}
// Check time of day (convert to hours)
const hour = new Date(time).getUTCHours();
return hour >= 9 && hour <= 17; // Business hours UTC

// Time-based routing
const now = new Date(utc_timestamp);
return now.getUTCDay() === 0 || now.getUTCDay() === 6; // Weekends
```

***

### Tags

#### `tags`

**Type:** Array of Strings\
**Description:** All tags assigned to the visitor (from `tag_` cookies)

```javascript theme={null}
// Check if visitor has specific tag
return tags.includes('vip_customer');

// Check multiple tags
return tags.includes('viewed_vsl') && tags.includes('clicked_cta');

// Has any tags
return tags.length > 0;
```

***

### IP Geolocation Data (Advanced)

To use IP geolocation data, your script must reference `ip_whois` - the system automatically loads this data only when needed for performance.

#### `ip_whois`

**Type:** Object\
**Description:** IP geolocation, connection and security information.

<Warning>
  **The country code lives on `ip_whois.country_code`, not `ip_whois.country`.** `country` holds the full country **name** (e.g. `"Spain"`). Timezone, ISP and proxy data are nested objects, not flat keys. These are the paths the built-in **Is From Country / State / EU / Timezone** and **Is Using VPN/Proxy** nodes generate, so matching them keeps hand-written rules consistent with the UI ones.
</Warning>

**Location**

* `ip_whois.country_code` — ISO country code (`'US'`, `'GB'`, `'DE'`)
* `ip_whois.country` — full country name (`'Spain'`)
* `ip_whois.continent`, `ip_whois.continent_code`
* `ip_whois.region` — region/state name · `ip_whois.region_code` — region/state code
* `ip_whois.city`
* `ip_whois.postal`
* `ip_whois.latitude`, `ip_whois.longitude`
* `ip_whois.is_eu` — boolean

**Timezone** (`ip_whois.timezone` is an object)

* `ip_whois.timezone.id` — IANA ID (`'Europe/Madrid'`)
* `ip_whois.timezone.abbr`, `.is_dst`, `.offset`, `.utc`

**Connection** (`ip_whois.connection` is an object)

* `ip_whois.connection.isp` — ISP name
* `ip_whois.connection.org` — organisation
* `ip_whois.connection.asn` — AS number
* `ip_whois.connection.domain`

**Security** (`ip_whois.security` is an object)

* `ip_whois.security.proxy`, `.vpn`, `.tor`, `.anonymous`, `.hosting`

Also present: `ip_whois.ip`, `ip_whois.type` (`IPv4`/`IPv6`), `ip_whois.success`.

<Warning>
  Using `ip_whois` adds \~10-20ms to script execution time as it requires a geolocation lookup. The lookup only runs if the literal string `ip_whois` appears in your script — so remove the reference entirely when you do not need it.
</Warning>

```javascript theme={null}
// Target specific countries
return ip_whois && (ip_whois.country_code == 'US' || ip_whois.country_code == 'CA');

// Block certain regions
return ip_whois && ip_whois.country_code != 'CN' && ip_whois.country_code != 'RU';

// Block VPNs, proxies and datacentre traffic
const sec = ip_whois && ip_whois.security;
return !!sec && sec.proxy != true && sec.vpn != true && sec.hosting != true;

// EU visitors
return ip_whois && ip_whois.is_eu == true;

// Timezone-based routing
return ip_whois && ip_whois.timezone.id == 'America/New_York';

// ISP-based routing
const isp = (ip_whois && ip_whois.connection && ip_whois.connection.isp) || '';
return isp.includes('Comcast') || isp.includes('Verizon');

// Block a known network by AS number
return !(ip_whois && ip_whois.connection && ip_whois.connection.asn == 32934);
```

<Tip>
  Security flags may come back as `true`/`false` **or** `1`/`0` depending on the lookup provider. Compare with `==` rather than `===`, or coerce with `!!`.
</Tip>

***

### Click Data (Advanced)

<Note>
  Click data is available when there's a click ID present. This is commonly used on upsells but can be available on any page with click tracking.
</Note>

#### `click_data`

**Type:** Object\
**Description:** Information about the original ad click

**Available Properties:**

* `click_data.time` - Click timestamp (Unix seconds)
* `click_data.seconds_ago` - Seconds since click
* `click_data.ip_address` - Click IP address (IPv4)
* `click_data.ip_address6` - Click IP address (IPv6)
* `click_data.ip_address_matches` - Does current IP match click IP

```javascript theme={null}
// Click must be recent (within 1 hour)
return click_data.seconds_ago < 3600;

// IP must match original click
return click_data.ip_address_matches === true;

// Old clicks only
return click_data.seconds_ago > 86400; // Over 24 hours

// Combined check
return click_data.ip_address_matches && click_data.seconds_ago < 1800; // Same IP within 30min
```

***

### Visit Data (Advanced)

To use visit data, your script must reference `visit_data` - the system automatically loads visitor behavior metrics when referenced.

#### `visit_data`

**Type:** Object\
**Description:** Comprehensive visitor behavior and history

**Available Properties:**

* `visit_data.first_visit` - First visit timestamp
* `visit_data.time_since_first_visit` - Milliseconds since first visit
* `visit_data.visit_count` - Total number of visits
* `visit_data.last_visit` - Last visit timestamp
* `visit_data.time_since_last_visit` - Milliseconds since last visit
* `visit_data.ip_address` - First visit IP (IPv4)
* `visit_data.ip_address6` - First visit IP (IPv6)
* `visit_data.session_id` - First session ID
* `visit_data.has_multiple_user_agents` - Used different browsers/devices
* `visit_data.unique_user_agent_count` - Number of different user agents
* `visit_data.page_visit_count_30min` - Page visits in last 30 minutes
* `visit_data.page_visit_count_all_time` - Total page visits ever
* `visit_data.unique_pages_visited` - Number of different pages visited
* `visit_data.average_time_between_visits` - Average time between visits (ms)
* `visit_data.direct_visits_count` - Visits without referrer
* `visit_data.referrer_visits_count` - Visits with referrer
* `visit_data.rapid_visits_detected` - Suspicious rapid visiting pattern

<Warning>
  Using `visit_data` adds \~100–300ms to script execution time because it loads visit history. Only use when behavior-based logic is essential.
</Warning>

```javascript theme={null}
// First-time visitors only
return visit_data.visit_count === 1;

// Returning visitors
return visit_data.visit_count > 1;

// Visited within last hour
const oneHour = 60 * 60 * 1000;
return visit_data.time_since_last_visit < oneHour;

// Visited long ago, re-engagement
const thirtyDays = 30 * 24 * 60 * 60 * 1000;
return visit_data.time_since_first_visit > thirtyDays && visit_data.visit_count > 1;

// Block suspicious behavior (bot detection)
return visit_data.rapid_visits_detected !== true && 
       visit_data.page_visit_count_30min < 20;

// High-intent visitors
return visit_data.unique_pages_visited >= 3 && visit_data.visit_count >= 2;

// Check if user switched devices (possible sharing)
return visit_data.has_multiple_user_agents === false;
```

***

## Debugging Script Rules

### Using the Debug Window

The best way to debug Script Rules is with the **Debug Window**. It shows what happens when your script runs.

**How to Debug:**

1. **Open the Debugger** - Click the **"Debugger"** button in the Page Builder or Page Events interface
2. This will open your page with the **Debug Window** automatically activated
3. **Navigate to "Page Events" tab** in the Debug Window to see Script Rule execution details
4. **Reload the page** if needed to trigger the Script Rule

**What You'll See:**

The Debug Window shows Script Rule details:

* **Result**: `TRUE` or `FALSE` - which path was taken
* **Execution Time**: How long the script took to run (in milliseconds)
* **Next Path**: Which branch the flow followed
* **Console Messages**: All your `console.log()`, `console.warn()`, and `console.error()` output
* **Errors**: Full error messages if the script failed
* **Used IP Whois**: Whether geolocation data was loaded
* **Used Click Data**: Whether click data was accessed
* **Has Customer Data**: Whether customer information was available
* **Script Preview**: First few lines of your script code
* **Full Context**: Complete evaluation data with all variable values

<Note>
  The Debug Window is the most efficient way to debug Script Rules. It shows you everything that happened during execution, including all console output and the exact data that was available.
</Note>

### Console Logging

You can use `console.log()` to debug your Script Rules:

```javascript theme={null}
console.log('Current country:', ip_whois.country_code);
console.log('Visit count:', visit_data.visit_count);
console.log('Is customer:', is_customer);

return ip_whois.country_code == 'US';
```

Console logs appear in the **Debug Window "Page Events" tab** with real-time, expandable details.

<Tip>
  Use console logging liberally during development to understand what data is available and how your conditions evaluate. Click "Debugger" in the Page Builder to open the Debug Window and see all logs.
</Tip>

**Example Debugging Session:**

```javascript theme={null}
// Log all available data to understand what you have
console.log('Query params:', query);
console.log('Is mobile:', is_mobile);
console.log('Is customer:', is_customer);
console.log('Visit count:', visit_data?.visit_count);
console.log('Country:', ip_whois?.country_code);

// Log your condition results
const isEligible = ip_whois.country_code == 'US' && visit_data.visit_count > 1;
console.log('Is eligible:', isEligible);

return isEligible;
```

Then in the Debug Window (opened by clicking "Debugger"), you'll see all these logs with their values, making it easy to spot issues with your logic.

For more details on using the Debug Window, see the [Debug Window documentation](/debugging/debug-window).

***

## Example Use Cases

### Example 1: Geographic Targeting

```javascript theme={null}
// US and Canada only, block VPNs
return (ip_whois.country_code == 'US' || ip_whois.country_code == 'CA') &&
       ip_whois.security.proxy != true &&
       ip_whois.security.hosting != true;
```

### Example 2: Customer Segmentation

```javascript theme={null}
// Returning customers who haven't visited in 30+ days
const thirtyDays = 30 * 24 * 60 * 60 * 1000;
return is_customer === true && 
       visit_data.time_since_last_visit > thirtyDays;
```

### Example 3: Anti-Fraud Protection

```javascript theme={null}
// Block suspicious patterns when click data is available
return click_data.ip_address_matches === true &&
       click_data.seconds_ago < 3600 &&
       visit_data.rapid_visits_detected !== true &&
       ip_whois.security.tor != true &&
       ip_whois.security.proxy != true;
```

### Example 4: Device & Platform Targeting

```javascript theme={null}
// iOS users only, version 14 or higher
return device.os === 'iOS' && 
       parseInt(device.os_version) >= 14 &&
       device.brand === 'Apple';
```

### Example 5: Behavior-Based Routing

```javascript theme={null}
// High-engagement visitors: viewed 3+ pages, visited 2+ times
return visit_data.unique_pages_visited >= 3 &&
       visit_data.visit_count >= 2 &&
       tags.includes('viewed_vsl');
```

### Example 6: Multi-Condition Affiliate Routing

```javascript theme={null}
// Specific affiliate from US, mobile device, first-time visitor
return session.aff_id === 'AFF123' &&
       ip_whois.country_code == 'US' &&
       is_mobile === true &&
       visit_data.visit_count === 1;
```

### Example 7: Time-Based Offers

```javascript theme={null}
// Weekend special offer (UTC)
const now = new Date(utc_timestamp);
const dayOfWeek = now.getUTCDay(); // 0 = Sunday, 6 = Saturday
return dayOfWeek === 0 || dayOfWeek === 6;
```

### Example 8: Tag-Based Progressive Disclosure

```javascript theme={null}
// Visitor watched VSL and clicked CTA but hasn't purchased
return tags.includes('watched_vsl') &&
       tags.includes('clicked_cta') &&
       is_customer === false;
```

***

## Best Practices

### Performance Optimization

1. **Avoid Heavy Operations When Possible**
   * Only reference `ip_whois` if you need geolocation
   * Only reference `click_data` if you need click attribution (requires click ID)
   * Only reference `visit_data` if you need behavior metrics

2. **Simple Checks First**
   ```javascript theme={null}
   // Good: Check simple conditions before heavy operations
   if (!is_customer) return false; // Fast check first

   // Then check heavy data
   return ip_whois.country_code == 'US';
   ```

3. **Use Tags for Behavior Tracking**
   ```javascript theme={null}
   // Show different upsell based on whether they watched the VSL
   // Tag 'watched_vsl' is set on VSL page when video completes
   return tags.includes('watched_vsl');
   ```

### Logic Clarity

1. **Comment Your Code**
   ```javascript theme={null}
   // Route high-value traffic: US/CA, mobile, new visitors
   return (ip_whois.country_code == 'US' || ip_whois.country_code == 'CA') &&
          is_mobile === true &&
          visit_data.visit_count === 1;
   ```

2. **Break Complex Logic into Steps**
   ```javascript theme={null}
   // Check geographic eligibility
   const isEligibleCountry = ip_whois.country_code == 'US';

   // Check device requirements
   const isCorrectDevice = is_mobile && !is_tablet;

   // Check behavior requirements
   const isNewVisitor = visit_data.visit_count === 1;

   return isEligibleCountry && isCorrectDevice && isNewVisitor;
   ```

3. **Use Meaningful Variable Names**
   ```javascript theme={null}
   const isVipCustomer = is_customer && customer.order_ids.length > 3;
   const isRecentVisit = visit_data.time_since_last_visit < (7 * 24 * 60 * 60 * 1000);

   return isVipCustomer && isRecentVisit;
   ```

### Error Handling

1. **Check for Null/Undefined**
   ```javascript theme={null}
   // Good: Check if data exists before using it
   return ip_whois && ip_whois.country_code == 'US';

   // Good: Array check
   return customer.order_ids && customer.order_ids.length > 0;
   ```

2. **Provide Fallback Values**
   ```javascript theme={null}
   // Fallback to false if data unavailable
   const country = ip_whois?.country_code || 'unknown';
   return country == 'US';
   ```

### Testing

1. **Test Both Paths**
   * Verify the `true` path works as expected
   * Verify the `false` path works as expected
   * Test edge cases (missing data, null values, etc.)

2. **Use Debug Window**
   * Click "Debugger" in Page Builder or Page Events to open Debug Window
   * View console logs and script execution details in the "Page Events" tab

3. **Test with Different IPs/Devices**
   * Use VPN to test different countries
   * Use browser dev tools to simulate mobile devices
   * Test with different referrers and query parameters

***

## Troubleshooting

### Script Returns Unexpected Results

**Problem:** Script always takes same path regardless of data

**Solutions:**

1. **Use the Debug Window** - Click "Debugger" in the Page Builder or Page Events to see the actual result and all data
2. Check your return statement - must return boolean
3. Use `console.log()` to debug variable values
4. Verify data is available (not null/undefined)
5. Check for typos in property names

```javascript theme={null}
// Debug example - add these logs and check Debug Window
console.log('Country:', ip_whois?.country_code);
console.log('Visit count:', visit_data?.visit_count);
console.log('Is customer:', is_customer);

return ip_whois.country_code == 'US';
```

Then check the Debug Window → Page Events tab to see:

* The actual `Result` (TRUE or FALSE)
* All your console logs
* What data was actually available
* The exact path taken (`Next Path`)

### Script Execution Errors

**Problem:** Script fails and takes `false` path

**Solutions:**

1. **Check Debug Window** - Click "Debugger" in the Page Builder to see the exact error message
2. Check for syntax errors in your code
3. Look at the error details in Debug Window → Page Events → script\_rule event
4. Ensure you're not using unsupported JavaScript features
5. Verify all referenced variables exist

**Debugging Steps:**

1. Click **"Debugger"** in the Page Builder or Page Events interface
2. The Debug Window will open automatically
3. Go to **Page Events** tab
4. Find the `script_rule` event with red/error status
5. Look at the **Error** field for the exact error message
6. Check **Full Context** to see what data was available

**Common Errors:**

```javascript theme={null}
// Bad: Using unsupported features
const result = array.flatMap(x => x);  // flatMap not supported

// Good: Use supported methods
const result = array.map(x => x);

// Bad: Undefined variable
return customVariable === true;  // customVariable doesn't exist

// Good: Use available variables
return is_customer === true;
```

The Debug Window will show you the exact line and error type, making it much easier to fix.

### Slow Performance

**Problem:** Page loads slowly when script rule executes

**Solutions:**

1. Remove `ip_whois` reference if not needed
2. Remove `click_data` reference if not needed (requires click ID to be present)
3. Remove `visit_data` reference if not needed
4. Simplify logic to avoid heavy operations

```javascript theme={null}
// Slow: Uses all heavy operations
return ip_whois.country_code == 'US' &&
       click_data.seconds_ago < 3600 &&
       visit_data.visit_count > 1;

// Fast: Use simple checks only
return query.country === 'US' && is_customer === true;
```

### Data Not Available

**Problem:** `ip_whois`, `click_data`, or `visit_data` is empty/null

**Solutions:**

1. **ip\_whois**: Make sure you reference it in your script (triggers lookup)
2. **click\_data**: Only available when there's a click ID present
3. **visit\_data**: Data may not be available for first-time, brand-new visitors

```javascript theme={null}
// Safe check with fallback
if (!ip_whois || !ip_whois.country_code) {
    return false; // Default behavior if geolocation fails
}

return ip_whois.country_code == 'US';
```

***

## JavaScript Limitations

Script Rules run inside an isolated JavaScript sandbox — a fresh interpreter per execution, with no network, no filesystem and no access to the host process. That isolation sets the limits below.

### Sandbox limits

| Limit | Value |
| - | - |
| Execution time | 5 seconds — the script is interrupted past that |
| Memory | 8 MB |
| Stack | 512 KB |
| `eval()` / `new Function()` | Disabled |

A script that throws is treated as **false**, so the flow takes Output 2. The error and any `console` output are captured and shown in the [Debug Window](/debugging/debug-window).

<Note>
  Your code is wrapped in a function before it runs, which is why it must **`return`** a value rather than just evaluate an expression. Write the body only — no `function` declaration of your own.
</Note>

### Supported Features

* Basic JavaScript syntax (ES5 + some ES6)
* Variables (`let`, `const`, `var`)
* Functions and arrow functions
* Arrays and objects
* Loops (`for`, `while`, `forEach`)
* Conditionals (`if`, `switch`, `ternary`)
* Comparison and logical operators
* `Math`, `Date`, `JSON` objects
* `String` and `Array` methods (most common ones)
* `console.log()` for debugging

### NOT Supported

* Async/await operations
* Promises
* Fetch API or HTTP requests
* Browser APIs (window, document, localStorage, etc.)
* ES6+ features like `flatMap`, `Object.fromEntries`
* Regular expressions with some advanced features
* Modules and imports

### Polyfills Included

The following are polyfilled automatically:

* `Array.prototype.includes()`
* `String.prototype.includes()`

<Warning>
  Always test your script rules thoroughly. If unsure about a JavaScript feature, test it with simple logic first before deploying to production.
</Warning>

***

## Related Documentation

* [Debug Window](/debugging/debug-window) - Learn how to debug Script Rules with the Debug Window
* [Page Events](/funnels/page-events) - Overview of the Page Events system
* [Page Events Node Reference](/funnels/page-events-nodes) - Every node type and its fields
* [Query Parameter Conditions](/funnels/query-parameters) - Simpler alternative for URL parameter checks
* [Content Visibility Control](/pages/visitor-based-content) - Using whitelisting with containers
* [Dynamic Content](/funnels/dynamic-content) - Personalizing content based on conditions
* [Exit Popups](/funnels/exit-popups) - Behavior-based exit intent detection

<Note>
  Start with simple Script Rule logic. Add complexity only when you can test each branch and see the expected result in the Debug Window.
</Note>


# Sequence Nodes
Source: https://docs.elasticfunnels.io/funnels/sequence-nodes

Organize complex page event flows with sequence nodes for better control and execution order

Sequence nodes help you organize complex page event flows by ensuring actions execute in the correct order. Think of them as "for each" loops that process connected nodes one by one.

## Understanding Sequence Nodes

A sequence node acts as an **organizational container** that executes all connected nodes in a specific order before proceeding to the next step in your flow.

### How Sequences Work

* **Sequential execution** - Processes each connected node completely before moving to the next
* **Top to bottom** - Executes nodes from top to bottom when multiple nodes are connected
* **Completion control** - Waits for all nodes to complete before continuing the flow
* **Flow organization** - Helps structure complex logic into manageable chunks

### Why Use Sequences?

* **Ensure execution order** - Critical when some actions depend on others
* **Organize complex flows** - Group related actions together
* **Improve debugging** - Easier to track where issues occur
* **Better visual organization** - Makes page event flows cleaner and more readable

## Basic Sequence Usage

### Creating a Sequence

1. Go to **Page Events** for your page
2. Click **"Add Node"**
3. Select **"Sequence"**
4. Connect the nodes you want to execute in sequence
5. Connect the sequence to your main flow

### Simple Example

**Without Sequence** (execution order not guaranteed):

```
Query Parameter Condition → Whitelist Visitor
                          → Split Test Component
                          → Dynamic Content
```

**With Sequence** (guaranteed order):

```
Query Parameter Condition → Sequence → Whitelist Visitor
                                    → Split Test Component  
                                    → Dynamic Content
```

## Advanced Sequence Patterns

### Multi-Step Whitelisting

Ensure visitors are properly whitelisted before showing content:

**Flow**:

1. **Query Parameter Condition** (`vtID` is not empty)
2. **Sequence** contains:
   * Whitelist Visitor
   * Log Visitor Data
   * Split Test Component
3. **Continue** to next flow step

### Conditional Actions

Perform multiple actions based on a single condition:

**Flow**:

1. **Script Rule** (check affiliate ID = 100)
2. **Sequence** contains:
   * Dynamic Container (show special pricing)
   * Log Affiliate Visit
   * Set Custom Tracking
3. **Continue** to purchase flow

### Data Processing

Process visitor data in a specific order:

**Flow**:

1. **Page Load**
2. **Sequence** contains:
   * Capture Visitor Info
   * Validate Data
   * Store in Database
   * Send to Analytics
3. **Continue** to page display

## Best Practices

### When to Use Sequences

* **Multiple dependent actions** - When action B depends on action A completing
* **Data processing** - When you need to process information in steps
* **Complex conditions** - When you have multiple actions after a condition
* **Clean organization** - When your flow is getting complex and hard to follow

### When NOT to Use Sequences

* **Single actions** - Don't use sequences for just one node
* **Independent actions** - When actions don't depend on each other
* **Simple flows** - When your flow is already clear and simple
* **Performance critical** - When you need maximum speed (sequences add slight overhead)

### Organization Tips

* **Group related actions** - Put logically related nodes in the same sequence
* **Use descriptive names** - Name your sequences clearly (e.g., "Affiliate Processing")
* **Keep sequences focused** - Don't put too many unrelated actions in one sequence
* **Document complex flows** - Add comments explaining what each sequence does

## Integration with Other Features

### Whitelisting Workflows

Sequences are perfect for complex whitelisting scenarios:

**Example**: Affiliate-specific whitelisting

```
Query Parameter Condition (affID exists) → Sequence:
                                           - Validate Affiliate ID
                                           - Whitelist Visitor
                                           - Log Affiliate Visit
                                           - Set Tracking Variables
```

### Split Testing

Use sequences to set up conditions before split testing:

**Example**: Conditional split testing

```
Query Parameter Condition (vtID = k) → Sequence:
                                       - Whitelist Visitor
                                       - Set Test Variables
                                       - Split Test Component
```

### Dynamic Content

Prepare data before showing dynamic content:

**Example**: Personalized content

```
Script Rule (check user type) → Sequence:
                                 - Load User Data
                                 - Determine Content Type
                                 - Dynamic Container
                                 - Track Personalization
```

## Common Sequence Patterns

### Authentication Flow

```
Page Load → Sequence:
            - Check Authentication
            - Validate Session
            - Load User Preferences
            - Set User Interface
```

### Affiliate Processing

```
Query Parameter Condition → Sequence:
                            - Validate Affiliate ID
                            - Set Tracking Variables
                            - Log Affiliate Visit
                            - Apply Affiliate Settings
```

### Purchase Preparation

```
Form Submit → Sequence:
              - Validate Form Data
              - Calculate Pricing
              - Set Payment Variables
              - Prepare Checkout
```

### Error Handling

```
Script Rule (error detected) → Sequence:
                               - Log Error Details
                               - Set Error Message
                               - Redirect to Error Page
                               - Send Error Notification
```

## Troubleshooting

### Common Issues

* **Sequence not executing** - Check that nodes are properly connected to the sequence
* **Wrong execution order** - Verify the vertical order of nodes connected to the sequence
* **Sequence hanging** - Check if any connected nodes are causing infinite loops
* **Performance issues** - Consider if you have too many nodes in a single sequence

### Debugging Sequences

1. **Test individual nodes** - Make sure each node in the sequence works independently
2. **Check execution order** - Verify nodes execute in the expected order
3. **Monitor completion** - Ensure all nodes complete before the sequence continues
4. **Use browser tools** - Check console for any JavaScript errors
5. **Test with different data** - Verify the sequence works with various inputs

### Performance Considerations

* **Minimize unnecessary sequences** - Don't use sequences unless needed
* **Optimize node order** - Put faster nodes first when possible
* **Avoid blocking operations** - Don't put long-running operations in sequences
* **Consider parallel execution** - Some actions might be better executed in parallel

## Advanced Usage

### Nested Sequences

You can connect sequences to other sequences for complex workflows:

```
Main Sequence → Sub-sequence 1 → Action A
                                → Action B
              → Sub-sequence 2 → Action C
                                → Action D
```

### Conditional Sequences

Use different sequences based on conditions:

```
Query Parameter Condition → Sequence A (for affiliates)
                          → Sequence B (for direct traffic)
```

### Loop-like Behavior

While not true loops, sequences can simulate iterative processing:

```
Sequence → Process Data Chunk 1
        → Process Data Chunk 2
        → Process Data Chunk 3
        → Final Processing
```

## Real-World Examples

### E-commerce Flow

```
Add to Cart → Sequence:
              - Validate Product Availability
              - Calculate Shipping
              - Apply Discounts
              - Update Cart Total
              - Prepare Checkout
```

### Lead Generation

```
Form Submit → Sequence:
              - Validate Email Address
              - Check for Duplicates
              - Add to Email List
              - Send Welcome Email
              - Redirect to Thank You Page
```

### Content Personalization

```
Page Load → Sequence:
            - Detect User Location
            - Load User Preferences
            - Apply Personalization Rules
            - Display Personalized Content
            - Track Personalization Event
```

<Note>
  Use sequences where execution order matters or where grouping related actions makes the flow easier to read. Too many sequences can make a flow harder to debug.
</Note>


# Split Testing
Source: https://docs.elasticfunnels.io/funnels/split-testing

Component split tests: swap a section of a page between variants and measure the result

A **component split test** replaces one section of a page — a headline, a video block, a pricing table — with a different saved component per visitor, and reports on the result.

It has two halves:

1. A **`<split-test>` container** in the page marks *where* the swap happens.
2. A **Component Split Test** node in [Page Events](/funnels/page-events) defines *what* the variants are and how traffic splits.

<Note>
  Testing whole pages instead of a section? See [Page Variants](/pages/page-variants) and [Funnel Split Testing](/funnels/funnel-split-testing), and the [comparison below](#which-kind-of-test-do-i-want).
</Note>

***

## Step 1 — Put a container on the page

The container is an empty slot identified by an **`id`**. It also carries a **`name`**, which is the label you will pick from in Page Events.

### In the page builder

Drag the **Split Test Container** block (Funnels category) onto the page, then set its **Split Test Container Name** trait. The builder writes it as a `<split-test>` element with the name stored on the component.

### On a coded page

```html theme={null}
<split-test id="headline-test" name="Headline Test">
  <!-- Fallback: shown when no Component Split Test node resolves a variant -->
  <component type="headline-variant-a"></component>
</split-test>
```

| Attribute | Required | Description |
| - | - | - |
| `id` | Yes | What the Page Events node stores and what the renderer matches on. Must be unique on the page. |
| `name` | Yes | Human-readable label shown in the Page Events container dropdown. |

<Warning>
  **On coded pages the attribute order is fixed.** The container list is built by scanning the page HTML for `<split-test id="…" name="…">` — `id` must come first, immediately followed by `name`, both in double quotes, with no other attributes between them. Written any other way, the container still renders but **will not appear in the Page Events dropdown**.
</Warning>

Anything inside the tag is the **fallback**: it renders unchanged whenever no variant is resolved.

### Listing container IDs

The builder populates its dropdown from:

```
GET /api/brands/{brand}/pages/{page}/component-type/split-test-container
```

```json theme={null}
[ { "id": "headline-test", "name": "Headline Test", "type": "split-test-container" } ]
```

The `id` in that response is exactly what goes into the node's `container` field.

<Note>
  The type segment is `split-test-container`, not `split-test`. `<split-test>` is the HTML tag; `split-test-container` is the component type. The same endpoint serves `dynamic-container` and `form`.
</Note>

***

## Step 2 — Create the variant components

Each variant is a **saved component**. In the page builder, right-click an element and choose **Create a new component** (or build one from scratch), then repeat for each variant. What matters downstream is the component's **code** — that is what the node stores.

***

## Step 3 — Wire the nodes

Open **Manage Page Events** for the page. A component split test is always the same three-level shape:

```mermaid theme={null}
flowchart LR
  E[Loaded] --> CST[Component Split Test<br/>container: headline-test<br/>value: 2]
  CST -->|Output 1| W1[Traffic Distribution<br/>50%]
  CST -->|Output 2| W2[Traffic Distribution<br/>50%]
  W1 --> C1[Component<br/>headline-variant-a<br/>baseline]
  W2 --> C2[Component<br/>headline-variant-b]
```

<Steps>
  <Step title="Add the Component Split Test node">
    Connect it to the entry node or to a condition. Set:

    * **Container** — the `<split-test>` container. Stored as `container`. The node warns *"Container is required"* until it is set.
    * **Total Variants** — `2` to `5`. Stored as `value`.
    * **Name** — used in split-test reporting.
  </Step>

  <Step title="Let it create the weights">
    Changing **Total Variants** adds an output pin **and a Traffic Distribution node** for each variant automatically. Reducing the count removes both the pin and the node attached to it.
  </Step>

  <Step title="Set the traffic split">
    Each **Traffic Distribution** node holds a percentage (`value`, 0–100) and a variant **name**. Editing one weight redistributes the remainder evenly across its siblings, so two variants land on 50/50 by default.
  </Step>

  <Step title="Attach one Component per weight">
    Under each Traffic Distribution node attach a **Component** node and pick the component. Turn on **Set as Baseline** on the control — that is the variant everything else is compared against.
  </Step>
</Steps>

<Warning>
  The **Component Split Test node ends its branch.** It performs the swap and stops. Anything you wire after it — rather than under a Traffic Distribution node — never runs.
</Warning>

### Wiring constraints

| Node | Can only attach to |
| - | - |
| **Traffic Distribution** (`split_test_weight`) | a **Component Split Test** or **Split Test** node |
| **Component** (`component_split_test_component`) | a **Traffic Distribution** node |

Only one Component per Traffic Distribution node, and only one Traffic Distribution per output pin.

Field-by-field detail: [Node Reference → Split testing](/funnels/page-events-nodes#split-testing).

***

## Worked example — split test a headline

**The page**

```html theme={null}
<split-test id="headline-test" name="Headline Test">
  <component type="headline-a"></component>
</split-test>
```

**The components**

| Code | Content |
| - | - |
| `headline-a` | `<h1>Buy Now</h1>` — the control |
| `headline-b` | `<h1>Buy Now and Save 50% Today</h1>` — the challenger |

**Page Events**

1. **Loaded** → **Component Split Test**
   * Container: `Headline Test`
   * Total Variants: `2`
   * Name: `Headline — hero`
2. Output 1 → **Traffic Distribution** — name `Control`, `50`
3. Output 2 → **Traffic Distribution** — name `Discount angle`, `50`
4. Under *Control* → **Component** `headline-a`, **Set as Baseline** on
5. Under *Discount angle* → **Component** `headline-b`

Save. The split-test record is created on save, and the node gains a **View Results** link.

**What the visitor receives**

```html theme={null}
<div data-sid="41" data-fnid="17" data-cid="982">
  <h1>Buy Now and Save 50% Today</h1>
</div>
```

* `data-sid` — the split test ID
* `data-fnid` — the Page Events node ID
* `data-cid` — the component ID that was served

The tracking script reads those attributes to record the view, and the assignment is attached to any conversion in the same session.

***

## How a variant is chosen

<Steps>
  <Step title="Declared winner wins outright">
    If a variant has been marked as winner, every visitor gets it and the weights are ignored. Marking a winner writes that Traffic Distribution node's `node_code` onto the parent as `winner_node_code`.
  </Step>

  <Step title="Otherwise, a returning visitor keeps their variant">
    The assignment is stored in a cookie named `st_res_<split_test_id>` (7 days, `httpOnly`) and mirrored into the session. If the stored component no longer exists in the test, the assignment is discarded and re-run.
  </Step>

  <Step title="Otherwise, exact rotation">
    New visitors are allocated from a **shared counter** rather than a per-visitor dice roll, so the live ratio tracks your configured weights closely instead of converging on them slowly. The counter is Redis-backed, so it holds across workers and servers; a weighted random draw is the fallback if that is unavailable.
  </Step>
</Steps>

<Note>
  Changing the weights or adding/removing a variant resets the rotation counter for the test. Existing visitors keep their cookie until it expires.
</Note>

**When nothing is resolved**, the `<split-test>` block is left exactly as authored and its inner content renders. That happens if no Component Split Test node targets the container, if the container `id` does not match, or if the node has no `split_test_id` yet (which is the case before the first save, and if the plan does not include split tests).

***

## Advanced settings

**Advanced Settings** on the Component Split Test node opens the statistical configuration for the underlying split test record: test duration, sample-size limits, significance level, statistical power, minimum detectable effect, multiple-testing correction, statistical method, primary metric, secondary metrics to watch (`winner_selection_criteria`), guardrail metrics, automated winner selection, and **custom goals**.

Custom goals are `{ name, value }` pairs where `value` must match an interaction name defined in the page builder.

Once the node has a `split_test_id`, saving this modal writes straight through to the split test record. Interpreting the results is covered in [Split Test Analytics](/analytics/split-test).

### Enforce Exact Split

The **Enforce Exact Split** checkbox stores `enforce_exact_split` on the node.

<Note>
  The current renderer does not read this flag. Component split tests already allocate traffic exactly, via the shared counter described above — leaving the box unchecked does not make allocation random.
</Note>

***

## Which kind of test do I want?

| | **Component Split Test** | **Load Another Page** (`page_variant`) | **Split Test** (`split_test`) |
| - | - | - | - |
| **What varies** | One container inside one page | The entire page body | A whole branch of the flow |
| **URL** | Unchanged | Unchanged — the other page renders at the same URL | Unchanged or changed, depending on what each branch does |
| **Set up as** | `component_split_test` → weights → components | A `page_variant` node on a branch | `split_test` → weights → whatever each branch does |
| **Runs on** | Server only | Server only | Server or browser |
| **Use when** | You are testing copy, an image, a video block, a pricing table | You are testing a materially different page but want one URL | You are testing whole paths, or combining a page test with other actions |

**Rules of thumb**

* Testing **one section**? Component split test. It is the cheapest to build and the easiest to read.
* Testing a **whole page layout**? Build the alternative as a page variant and select it with **Load Another Page**. To split traffic between variants, put a **Split Test** node in front and hang a **Load Another Page** under each Traffic Distribution node.
* Need the variants to have **their own page events**? Turn on **Load & Override Page Events** on the Load Another Page node. Left off, the variant inherits the primary page's events.
* Testing **different steps of a funnel** rather than different renderings of one step? That is [Funnel Split Testing](/funnels/funnel-split-testing).

<Warning>
  Do not stack a component split test and a page-variant test on the same page at the same time unless you want a factorial design. Two overlapping tests make each one's numbers much harder to read.
</Warning>

***

## Inline split tests (coded pages)

Use `<inline-split-test>` when you want to A/B test content **directly in the HTML** without creating separate components or configuring Page Events. Variants and their content live inside the tag itself.

<Note>
  This is the simplest way to split test on coded pages. For component-based variants, multi-variant reporting or anything driven by conditions, use the `<split-test>` container above.
</Note>

### Syntax

```html theme={null}
<inline-split-test name="My Test">
    <variant name="variant a" weight="50">
        <!-- HTML for variant A -->
    </variant>
    <variant name="variant b" weight="50">
        <!-- HTML for variant B -->
    </variant>
</inline-split-test>
```

**Attributes**

| Element | Attribute | Required | Description |
| - | - | - | - |
| `<inline-split-test>` | `name` | Yes | Human-readable name for the split test. Used as the record name in the database and analytics dashboard. The tag is ignored on save if `name` is missing. |
| `<inline-split-test>` | `id` | Auto-generated | Database record ID. Injected automatically on save — do not set or edit manually. The runtime needs it: a tag without an `id` is left untouched. |
| `<variant>` | `name` | Yes | Unique name for the variant. Used to identify and track the variant across saves. |
| `<variant>` | `weight` | No | Traffic percentage (0–100). If no variant carries a positive weight, traffic splits evenly. |

### Basic example (equal split)

```html theme={null}
<inline-split-test name="Headline Test">
    <variant name="short headline">
        <h1>Buy Now</h1>
    </variant>
    <variant name="long headline">
        <h1>Buy Now and Save 50% Today</h1>
    </variant>
</inline-split-test>
```

This creates a 50/50 split. For three variants it would be 33/33/34, and so on.

### Weighted example

```html theme={null}
<inline-split-test name="Headline Test">
    <variant name="control" weight="70">
        <h1>Original Headline</h1>
    </variant>
    <variant name="challenger" weight="30">
        <h1>New Headline</h1>
    </variant>
</inline-split-test>
```

Weights must sum to 100. If **some** variants carry a positive weight, any variant left without one is treated as `0` and receives no traffic.

### Saving pages through the API

When you create or update a coded page through the public Pages API:

* Send the full `<inline-split-test>...</inline-split-test>` block inside the `html` field.
* The Pages API stores that source HTML as provided.
* The create/update response does **not** replace the tag with the winning variant's runtime HTML.
* The public Pages API also does **not** inject the auto-managed `id` attribute as part of `POST /api/brands/{brand}/pages` or `PUT /api/brands/{brand}/pages/{page}`.

If the page is saved through the editor save flow instead, the server normalises the tag, injects the generated `id`, and returns the updated HTML.

<Warning>
  If an API or editor save response returns normalized inline split test HTML with an injected `id`, persist that returned HTML and use it for future updates. This matters only when you send `html` again on a later save or update. If `html` is omitted because nothing changed, the existing stored HTML remains unchanged. If you do send `html` again and keep using the original `<inline-split-test>` block without the server-generated `id`, the server can treat it as a new inline split test and create a new split test record on every save.
</Warning>

### How it works

1. **On editor save**, the system validates the tag structure (the `<inline-split-test>` must have a `name`, and there must be at least 2 `<variant>` tags each with a `name`). It creates a split test database record and injects an `id` attribute into the tag.

2. **At runtime**, the server checks the `st_res_{id}` cookie or session for an existing assignment; if there is none it selects a variant using the same deterministic weighted rotation as component split tests, sets a 7-day cookie, and replaces the whole block with just the chosen variant's HTML.

3. **Tracking** is automatic — the rendered output carries `data-sid` and `data-cid`, which the built-in tracking script turns into `split-test-view` events.

4. **Conversion attribution** works out of the box: the split test ID is pushed into the session's `sids` list and travels with conversion and click payloads.

### Server output

```html theme={null}
<div data-sid="[split_test_id]" data-cid="[variant_code]">
    <!-- HTML of the chosen variant -->
</div>
```

The `variant_code` is an internal identifier (`v0`, `v1`, …) that maps back to the variant name in the analytics dashboard.

### Rules

* The `<inline-split-test>` tag must have a **`name`** attribute. Tags without a name are ignored on save.
* Minimum **2 variants** required, each with a unique **`name`**. With fewer than two the tag is left as-is at runtime.
* Do not manually set or edit the **`id`** attribute — it is managed by the system.
* **Removing the tag** from the page does **not** delete or deactivate the split test record. Use the split test management UI to deactivate it.
* **Variant identity is tracked by name.** Existing variants keep their internal code (`v0`, `v1`, …) across saves. Renaming a variant creates a new one; the original and its data remain in the record.

***

## Tips

* Test one element at a time so the result is attributable.
* Name the test and every variant — those names are what you read in reporting.
* Mark a baseline. Comparisons are meaningless without a declared control.
* Let the test reach the sample size you configured before declaring a winner.
* When you do declare a winner, the winning variant is served to everyone immediately.

***

## Related

<CardGroup>
  <Card title="Node Reference" href="/funnels/page-events-nodes" />

  <Card title="Page Events" href="/funnels/page-events" />

  <Card title="Dynamic Content" href="/funnels/dynamic-content" />

  <Card title="Page Variants" href="/pages/page-variants" />

  <Card title="Funnel Split Testing" href="/funnels/funnel-split-testing" />

  <Card title="Split Test Analytics" href="/analytics/split-test" />
</CardGroup>


# Trigger Pages
Source: https://docs.elasticfunnels.io/funnels/trigger-pages

Define which pages can start a funnel — the first step after entry in the funnel builder.

**Trigger pages** are the pages that can **start** a funnel. They correspond to the first page (or page group) right after the **entry** node in the funnel builder. Only visits that land on one of these pages are considered to be "in" this funnel from the start.

## Why trigger pages matter

* They define the **entry points** for the funnel (e.g. which VSL or landing page URLs count as the start of this funnel).
* They stay in sync with the funnel flow: when you change the flow in the builder (e.g. connect entry to different pages), trigger pages are updated automatically when you save the builder.
* When you edit them in the funnel form (**Trigger pages** tab), saving updates both the stored list and the flow so the builder and the form always match.

## Where to set them

When creating or editing a funnel, open the funnel form (e.g. from the Funnels list). The form has three tabs:

1. **General** — Title, status, domains.
2. **Trigger pages** — List of pages that can start this funnel.
3. **Trigger Rules** — When to use this funnel (e.g. by country, affiliate, or query). See [Trigger Rules](/funnels/trigger-rules).

In the **Trigger pages** tab you can:

* See the currently selected trigger pages as removable tags.
* Click **Add Page** to open a searchable dropdown and add one or more pages.
* Remove a page by clicking the × on its tag.
* Save the funnel — the flow (the node connected to entry in the builder) is updated to match.

If the funnel has any trigger pages (or trigger rules), the tab shows an **orange badge** with the count so you can see at a glance that they're configured.

## How they relate to the funnel builder

In the **funnel builder**, the **entry** node is the start of the flow. The node(s) connected directly from entry are either:

* A single **page** node — that page is the only trigger page.
* A **page group** node — the pages in that group are the trigger pages.

When you:

* **Save the funnel form** with changes to trigger pages — the app updates the flow so the entry connects to a page group (or single page) with exactly those pages.
* **Save the funnel builder** after changing which pages follow entry — the app updates the stored trigger pages list to match the flow.

So the **Trigger pages** tab and the **builder** always reflect the same set of entry pages once you save from either place.

## Summary

| What you do | What happens |
| - | - |
| Add/remove pages in the **Trigger pages** tab and save the funnel | Stored trigger pages and the flow (entry → page group) are updated. |
| Change the flow in the builder (e.g. connect entry to different pages) and save | Stored trigger pages are updated to match the flow. |
| Open a funnel that was created before trigger pages existed | Trigger pages are derived from the current flow; you can edit them in the tab and save to store them. |

For rule-based behavior (when to show this funnel by country, affiliate, or URL), see [Trigger Rules](/funnels/trigger-rules).


# Trigger Rules
Source: https://docs.elasticfunnels.io/funnels/trigger-rules

Show different funnels by country, affiliate, or URL parameters — when to use this funnel.

You can have **multiple funnels on the same domain**. One funnel is the **default** (fallback when no rules apply). Other funnels can be assigned to the same domain **with trigger rules** — they are used only when their conditions match (e.g. visitor country, affiliate, or URL parameters).

## How it works

* **One default per domain** — One funnel is the default when no rules apply (e.g. "main funnel" for everyone else). Default funnels don't use trigger rules.
* **Rule-based assignments** — Other funnels can be assigned to the same domain **without** being the default; add **Trigger rules** so they're used only when conditions match.
* **First match wins** — When a visitor lands on the domain, the system checks funnels that have trigger rules. The first funnel whose rules match is used. If none match, the default funnel is used.

<Info>
  The **Trigger Rules** tab is only available when the funnel is **not** set as the default for any domain. If this funnel is the default for at least one domain, you can't add rules (the default is the fallback).
</Info>

## When to use trigger rules

* **Different funnels by country or region** — e.g. US vs EU, or specific states/regions.
* **Different funnels per affiliate** — e.g. funnel A for affiliate 123, funnel B for affiliate 456.
* **URL parameters** — e.g. when `?affiliate_id=123` or another query parameter is present.
* **Combinations** — e.g. "US and affiliate X" or "country A OR country B" using AND/OR in the rule builder.

## Setting up trigger rules

1. Go to **Funnels** and edit the funnel (or create one).
2. In the **General** tab, under **Domains**, assign the domain. Do **not** turn on **Default Funnel for Domain** for this funnel if you want to use rules (or use rules only on other domain assignments).
3. Open the **Trigger Rules** tab. Use the rule builder to add conditions:
   * **Country** — Match by visitor country (e.g. US, GB).
   * **Region / State** — Match by region or state when available.
   * **Affiliate** — Choose an affiliate from your list (internal ID).
   * **Query parameter** — Enter any parameter name (e.g. `affiliate_id`, `pid`); the rule checks the URL query string.
4. Add multiple conditions and use **AND** / **OR** (and optional **groups**) to combine them.
5. Save. The funnel list will show **Default** (fallback) or **Default (with rules)** for each domain.

If the funnel has any trigger rules, the **Trigger Rules** tab shows an **orange badge** with the number of conditions.

## Default vs rule-based

| Type | Meaning |
| - | - |
| **Default** (no rules) | This funnel is used when no rule-based funnel matches. Only one such default per domain. |
| **Default (with rules)** | This funnel is used only when its trigger rules match (e.g. country, affiliate, or query param). You can have many of these per domain. |

The system always tries rule-based funnels first; if none match, it uses the single default for that domain. You can also force a specific funnel with the URL: `?f=[funnel code]`.

## Tips

* Keep the default funnel simple (e.g. your main offer). Use trigger rules for geo, affiliate, or campaign-specific flows.
* Use **Affiliate** when you want to match by a known affiliate from your list. Use **Query parameter** when you want to match on any URL parameter (e.g. `?affiliate_id=123` or `?pid=abc`).
* In the funnel list, the **Default (with rules)** badge shows which domain assignments use trigger rules.

For which pages can *start* a funnel (entry points), see [Trigger Pages](/funnels/trigger-pages).


# EF API (window.ef)
Source: https://docs.elasticfunnels.io/funnels/window-api

Use the global ef object in client scripts and on the page — tags, visibility, next step, and delays.

The **`window.ef`** object is available on every funnel page. Use it in **Client script** nodes, in inline scripts, or anywhere on the page to work with tags, visibility, flow control, and timing — without loading the full funnel engine.

<CardGroup>
  <Card title="Tags" icon="cookie" href="#tags">
    Add, check, or remove tags (same as Add tag / Has tag nodes).
  </Card>

  <Card title="Flow control" icon="code-branch" href="#flow-control">
    Advance to the next step from a client script with <code>ef.nextNode()</code>.
  </Card>

  <Card title="Visibility" icon="eye" href="#visibility">
    Check if an element is visible or wait until it appears.
  </Card>

  <Card title="Timing" icon="clock" href="#timing">
    Delay execution with <code>ef.wait()</code>.
  </Card>

  <Card title="Video" icon="video" href="#video">
    Check video progress (seconds or %) and run a callback when the CTA is shown.
  </Card>
</CardGroup>

***

## Where you can use it

* **Client script** node — Your script runs in the page; you can call `ef.addTag()`, `ef.nextNode()`, `ef.waitForVisible()`, etc. The flow does **not** auto-advance after a client script; call `ef.nextNode()` when you want to continue.
* **Any inline or page script** — `window.ef` is defined early, so you can use it in `onclick`, in a `<script>` block, or from other JS.
* **Click tracking** — Buttons or links with `data-ef-add-tag="tagname"` will add that tag when clicked (no client script needed).

***

## Tags

Tags are stored in cookies (same as the **Add tag** and **Has tag** nodes). Use the same tag name in the builder and in `ef` so conditions and scripts stay in sync.

### ef.addTag(name, expirationMinutes)

Sets a tag (stored in a cookie). Use after a conversion, CTA click, or in a client script.

* **name** — Tag name (same as in the **Add tag** node and **Has tag** condition).
* **expirationMinutes** — Optional. If omitted or `0`, the tag is a **session cookie** (cleared when the browser closes). If set to a positive number, the tag expires after that many minutes (e.g. `60` = 1 hour, `10080` = 7 days).

```javascript theme={null}
// Session cookie (cleared when browser closes)
ef.addTag('saw_popup');
ef.addTag('newsletter_signup');

// Expires after 60 minutes (1 hour)
ef.addTag('saw_popup', 60);

// Expires after 7 days (10080 minutes)
ef.addTag('campaign_click', 10080);
```

### ef.hasTag(name)

Returns `true` if the tag is set, `false` otherwise.

```javascript theme={null}
if (ef.hasTag('saw_popup')) {
  // Already saw the popup, skip
} else {
  // Show popup, then ef.addTag('saw_popup')
}
```

### ef.removeTag(name)

Removes the tag (deletes the cookie).

```javascript theme={null}
ef.removeTag('saw_popup');
```

***

## Flow control

### ef.nextNode()

Only meaningful inside a **Client script** node. Advances the funnel to the next step. You can call it immediately or later (e.g. after `ef.waitForVisible` or `ef.wait`).

<Note>
  In the client script you write <code>ef.nextNode()</code> with no arguments. The funnel engine replaces this with a call that knows the current node, so each script gets the correct "next" step.
</Note>

```javascript theme={null}
// Continue right away
ef.nextNode();
```

```javascript theme={null}
// Continue after something is visible
ef.waitForVisible('.thank-you-message', function() {
  ef.nextNode();
});
```

```javascript theme={null}
// Continue after a delay
ef.wait(2000, function() {
  ef.nextNode();
});
```

***

## Visibility

### ef.isVisible(selectorOrElement)

Returns `true` if the element exists and is visible (non-zero size, not `display: none`, not `visibility: hidden`, opacity > 0). Accepts a CSS selector string or a DOM element.

```javascript theme={null}
if (ef.isVisible('.banner')) {
  // Banner is on screen
}

var el = document.querySelector('#my-div');
if (ef.isVisible(el)) {
  // Element is visible
}
```

### ef.waitForVisible(selector, callback)

Waits until an element matching the selector is in the DOM and visible, then runs the callback once. Works on refresh if the element is already visible. Returns a **cancel** function so you can stop waiting.

```javascript theme={null}
ef.waitForVisible('.thank-you-message', function() {
  ef.nextNode();
});
```

```javascript theme={null}
// Optional: cancel if needed
var cancel = ef.waitForVisible('.popup', function() {
  ef.nextNode();
});
// cancel(); // to stop waiting
```

***

## Timing

### ef.wait(ms, callback)

Runs the callback after `ms` milliseconds. Returns a **cancel** function (clears the timeout).

```javascript theme={null}
ef.wait(3000, function() {
  ef.nextNode();
});
```

```javascript theme={null}
var cancel = ef.wait(5000, function() {
  doSomething();
});
// cancel(); // to clear the timeout
```

***

## Video

These helpers use the same video state as the **Video progress check** and **On CTA** nodes (Vidalytics, TrackPlay, SmartPlayer, or main page video).

### ef.videoProgressCheck(opts)

Returns `true` if the video has reached the given position, `false` otherwise. **opts** is an object with either **`seconds`** or **`percent`** (or both).

* **seconds** — Target playback time in seconds (e.g. `30` = 30 seconds).
* **percent** — Target percentage of video length (e.g. `50` = 50%).

```javascript theme={null}
if (ef.videoProgressCheck({ percent: 50 })) {
  // Video is at or past 50%
}
if (ef.videoProgressCheck({ seconds: 30 })) {
  // Video is at or past 30 seconds
}
```

### ef.onCta(callback)

Runs your **callback** when the video CTA is shown (when `video-cta-shown` fires, e.g. from `getStarted()`). The callback receives the event detail (e.g. `{ focus_on_cta, timestamp }`). Returns an **unsubscribe** function.

```javascript theme={null}
ef.onCta(function(detail) {
  ef.nextNode();
});
var unsubscribe = ef.onCta(function() { /* ... */ });
// unsubscribe();
```

### ef.getVideoProgress()

Returns **`{ currentTime, duration, percent }`** for the main video. Same sources as the funnel video nodes.

```javascript theme={null}
var progress = ef.getVideoProgress();
```

***

## Client script examples

**Wait for an element, then continue:**

```javascript theme={null}
ef.waitForVisible('.order-confirmation', function() {
  ef.nextNode();
});
```

**Delay, then continue:**

```javascript theme={null}
ef.wait(2000, function() {
  ef.nextNode();
});
```

**Set a tag and continue:**

```javascript theme={null}
ef.addTag('completed_survey');
ef.nextNode();
```

**Branch in script (then continue when ready):**

```javascript theme={null}
if (ef.hasTag('saw_offer')) {
  ef.nextNode(); // go to next step
} else {
  ef.addTag('saw_offer');
  ef.waitForVisible('#offer-cta', function() {
    ef.nextNode();
  });
}
```

***

## Adding a tag from a click (no script)

Add `data-ef-add-tag="tagname"` to a link or button (or to a parent component with `data-cid`). When the user clicks, the tag is set automatically. Useful for "clicked CTA" or "opened modal" without a client script.

```html theme={null}
<button data-ef-add-tag="clicked_cta">Get started</button>
```

***

## Summary

| Method | Description |
| - | - |
| `ef.addTag(name, expirationMinutes?)` | Set a tag. Omit or use `0` for session cookie; use a positive number for expiration in minutes. |
| `ef.hasTag(name)` | Returns whether the tag is set. |
| `ef.removeTag(name)` | Remove the tag. |
| `ef.nextNode()` | Advance to the next step (use inside Client script). |
| `ef.isVisible(selectorOrElement)` | Returns true if the element is visible. |
| `ef.waitForVisible(selector, callback)` | Run callback when the element is visible; returns cancel. |
| `ef.wait(ms, callback)` | Run callback after ms milliseconds; returns cancel. |
| `ef.videoProgressCheck(opts)` | Returns true if video reached `opts.seconds` and/or `opts.percent`. |
| `ef.onCta(callback)` | Run callback when video CTA is shown; returns unsubscribe. |
| `ef.getVideoProgress()` | Returns `{ currentTime, duration, percent }` for the main video. |
| `ef.sub.upgrade(old, new)` | Upgrade subscription from one SKU to another. Returns Promise. See [Subscription Upsells](/products/subscription-upsells). |
| `ef.sub.cancel(reason)` | Cancel the current subscription. `reason` is optional and is recorded against the cancellation - pass the exit-survey answer so it reaches your churn reporting. Returns Promise. See [Subscription Upsells](/products/subscription-upsells). |
| `ef.sub.upgradeThenNavigate(old, new, url)` | Upgrade subscription then navigate, with loading overlay. |
| `ef.sub.cancelThenNavigate(url, reason)` | Cancel subscription then navigate, with loading overlay. `reason` is optional; without it the cancellation is recorded as "Not specified". |


# How to design a checkout page
Source: https://docs.elasticfunnels.io/guides/how-to-design-a-checkout-page

Build a checkout page from scratch: enable the checkout flag, resolve a product from the URL or a backend script, render single-product / cart / subscription blocks, wire wallets, the card panel, order bumps, and the formless submit.

This guide walks through building a working checkout page in the code editor (or page builder). It follows the real runtime: the same page can serve a **one-time** product, a **subscription**, or a multi-item **cart** depending on what the URL - or the page's own backend script - resolves, so most of the layout is built from conditionals that the browser evaluates against live checkout data.

For exact scope keys and totals, see [Checkout functionality reference](/checkouts/checkout-functionality-reference) and [Frontend Template Engine: Checkout](/frontend-template-engine/checkout). For wallet setup, see [Apple Pay and Google Pay](/merchants/apple-pay-google-pay).

<Info>
  The templates below mirror a real production checkout (`checkout.ef`). Every directive shown is copied from a page that renders correctly against a live merchant — not invented for the docs.
</Info>

***

## How a checkout page renders

Two passes build the page:

1. **Server pass (`CheckoutProcessor`).** Runs if the page has the "Is checkout page" flag on, **or** if the page's backend script named a product (see Step 1b). It resolves the product, builds the `checkout` scope (customer, totals, subscription, bumps, coupon, wallet settings), and **swaps the checkout tags** - `<checkout-cc-panel>` becomes a gateway-specific card `<div>`, `<checkout-wallet>` becomes the wallet containers. It injects the checkout payload onto `window.efScope.checkout`.
2. **Client pass (frontend template engine).** In the browser, it evaluates every block marked `data-frontend-template="true"` against the live scope (including values only known client-side, such as whether a wallet button actually rendered), fills the card/wallet forms, and wires the submit button.

<Warning>
  If **"Is checkout page" is off** and the page's backend script sets no product, `CheckoutProcessor` never runs. The tags are **not** swapped - `<checkout-cc-panel>` and `<checkout-wallet>` reach the browser as raw, inert custom elements, and `checkout.*` scope is empty. The page looks broken even with a valid merchant. This is the single most common reason a checkout "doesn't work."
</Warning>

***

## Prerequisites

1. **Enable "Is checkout page"** on the page. Open **Page List** → **Edit Page** → toggle **Is checkout page** on → Save. (A page that names its product in a backend script can skip this - see Step 1b.)
2. **Assign a merchant** to the domain (Settings → Domains → Edit → Merchant). The card panel is swapped for a gateway-specific form (Stripe / NMI / Authorize.Net) resolved from this merchant.
3. **Link at least one product** so the page can resolve something to sell - from `?p=<code>`, a cart, or a backend script.

<Warning>
  **"Is checkout page" is an app-only page setting.** It is stored on the page and toggled in the dashboard. It is **not** settable from the `ef` CLI, and `ef pages create` does **not** set it - a page pushed with the CLI still needs the toggle flipped in the app, *or* a `setVariable("checkout_product", …)` in its backend script, before checkout runs. Quiz pages that take payment must have this flag on **as well as** their quiz flag; the two are independent.
</Warning>

***

## Step 1 — resolve the product from the URL

A single-product checkout loads its product from the **`p` query parameter**: `/checkout?p=your-product-6-bottles`. The runtime reads `req.query.p`, looks the product up for the brand, and populates the `checkout` scope (title, image, price, retail price, and - if the product is a subscription - the full billing cadence).

So a checkout page reached this way is generic; **the `?p=` code decides what it sells.** A plan or quantity selector is just a set of links (or a script) that point at the same page with a different `p`:

```html theme={null}
<!-- Plan / quantity selector: each option is the same checkout page, different ?p= -->
<a href="/checkout?p=your-product-1-week">1 week</a>
<a href="/checkout?p=your-product-4-weeks">4 weeks - most popular</a>
<a href="/checkout?p=your-product-12-weeks">12 weeks - best value</a>
```

<Info>
  If there is **no** `p` in the URL, the page falls back to what its backend script named (Step 1b), and then to **cart-only mode** (see Step 2). A page with none of the three cannot resolve anything to sell.
</Info>

Because product resolution happens on the server, `checkout.subscription` and the totals are already correct on first paint — no client fetch. See [Buy links](/products/buy-links) for how funnel buttons build the `?p=` link.

***

## Step 1b - set the product from a backend script

A `?p=` in the URL assumes the buyer arrives from somewhere else - a landing page, a funnel button, a buy link. **A one-page VSL + checkout has no such link.** The visitor lands on the video, watches, and scrolls down to a checkout on the same page, so nothing ever put a product code in the URL.

For that shape, the page names its own product in a `<script scope="backend">` block:

```html theme={null}
<script scope="backend">
setVariable("checkout_product", "your-course-code");
</script>
```

That single line does three things:

1. **Resolves the product server-side**, exactly as `?p=` would - same title, image, price, retail price and subscription cadence in the `checkout` scope, correct on first paint.
2. **Turns the page into a checkout page.** You do *not* need the "Is checkout page" toggle. Naming a product *is* the flag, so the checkout tags get swapped and `checkout.*` is populated on a page the dashboard still lists as an ordinary one.
3. **Pins the selection to the session**, so the submit charges what the page rendered rather than whatever the browser posts back.

<Info>
  The rest of the guide applies unchanged. The order summary, card panel, wallets, bumps and the formless submit are all built exactly as in Steps 2-8 - only where the product came from is different.
</Info>

### Precedence: the script wins over `?p=`

When a page sets `checkout_product`, it **outranks** any `?p=` in the URL. That is deliberate rather than restrictive, because the backend sandbox already receives the query string - a page that wants the URL to decide simply says so:

```html theme={null}
<script scope="backend">
// URL wins when present, page default otherwise.
setVariable("checkout_product", request.query.p || "your-course-code");
</script>
```

Because the script is ordinary JavaScript, the same hook covers anything you can compute at render: a geo-priced variant, a returning customer's upgrade code, a split-test arm, an expired-deadline fallback.

```html theme={null}
<script scope="backend">
// Cheaper variant once the launch window closes.
var launchOver = Date.now() > Date.parse("2026-09-01T00:00:00Z");
setVariable("checkout_product", launchOver ? "your-course-standard" : "your-course-launch");
</script>
```

<Warning>
  Set `checkout_product` **or** `checkout_cart`, never both. A product code always wins and the cart is ignored, so setting both silently sells only the single product.
</Warning>

<Info>
  A page made a checkout page *only* by its backend script cannot be picked as a funnel's or merchant's **checkout page target** - the **Set Checkout Page** node validates the stored flag, which is still off. That is usually what you want, since such a page sells its own product rather than whatever a buy link asks for. If you need it in both roles, turn the "Is checkout page" toggle on as well; the script keeps working either way.
</Info>

### Selling several products from one page

Two ways, depending on whether the buyer chooses.

**A fixed bundle** - the page decides, the buyer does not. Use `checkout_cart` with `{ code, quantity }` lines. The order summary renders through the `is_cart` branch (Step 2) and the totals are the sum of the lines:

```html theme={null}
<script scope="backend">
setVariable("checkout_cart", [
    { code: "your-course-code",   quantity: 1 },
    { code: "your-workbook-code", quantity: 2 }
]);
</script>
```

Repeat a code and its quantities add up rather than producing a duplicate line; a line whose code is missing or malformed is dropped without taking the rest of the bundle with it.

**A cart the buyer fills** - the VSL offers several products and the visitor picks. Put `[ADD-TO-CART=<code>]` buttons in the page copy and leave `checkout_product` / `checkout_cart` unset; the checkout section below reads the cart the buttons built:

```html theme={null}
<a href="[ADD-TO-CART=your-course-code]">Add the course - $297</a>
<a href="[ADD-TO-CART=your-workbook-code]">Add the workbook - $47</a>
```

<Info>
  The buyer-filled cart lives in browser storage, so it survives a scroll but not a cleared browser. A fixed `checkout_cart` is resolved on the server every render and cannot be edited by the visitor at all - prefer it whenever the bundle is not the buyer's choice.
</Info>

### What the buyer cannot change

Whichever of the two the page sets, the resolved codes are pinned to the session against that page's id while it renders. On submit the runtime charges the pin, not the posted fields - so an edited form, a stale tab, or a hand-crafted POST cannot swap the product out from under a page that already showed a price. Pages that use `?p=` or a buyer-filled cart pin nothing and behave exactly as they always have.

<Info>
  Bumps are unaffected and stack on top of any of these. Configure them as in Step 7 - from page config or the **Set Checkout Bumps** node - and the buyer's selections are added to the pinned product or bundle at submit.
</Info>

***

## Step 2 — single product vs cart

The order-summary area renders one of two shapes, chosen by scope flags:

| Condition | When it's true | Data source |
| - | - | - |
| `is_single_product` | One product, from `?p=` or `checkout_product` | `checkout.product_image`, `checkout.product_title`, `checkout.product_price`, `checkout.retail_price` |
| `is_cart` | A multi-item **cart** is present | `<template-foreach data-each="item in cartItems">` with `[[ item.name ]]`, `[[ item.image ]]`, `[[ item.quantity ]]`, `[[ item.total ]]`, `[[ item.code ]]` |

<Info>
  **Most carts here are Shopify-style carts** - multi-item carts synced from Shopify. Most direct-response checkouts are single-product (one `?p=`); the `is_cart` branch exists so the same layout can also render a synced Shopify cart with per-line quantities and remove buttons. See [Shopify Checkout](/merchants/shopify-checkout). The same branch renders the two on-page multi-product shapes from Step 1b: a fixed `checkout_cart` bundle, and a cart the buyer fills with `[ADD-TO-CART=<code>]` buttons.
</Info>

Both branches must be marked `data-frontend-template="true"` (see Step 6 below). This is the exact production markup:

```html theme={null}
<div class="dt-co-card">
  <!-- Single product (from ?p=) -->
  <template-if data-condition="is_single_product" data-frontend-template="true">
    <div class="dt-co-prod-row">
      <div class="dt-co-prod-img-wrap">
        <template-if data-condition="checkout.product_image" data-frontend-template="true">
          <img ef-src="checkout.product_image" alt="Product" />
        </template-if>
        <template-else data-frontend-template="true">
          <span class="dt-co-prod-img-ph"><!-- placeholder icon --></span>
        </template-else>
        <span class="dt-co-prod-qty">1</span>
      </div>
      <div class="dt-co-prod-info">
        <p class="dt-co-prod-name"><span ef-text="checkout.product_title">Product</span></p>
      </div>
      <div class="dt-co-prod-price">
        <span class="dt-co-prod-price-old" ef-text="checkout.retail_price"></span>
        <span ef-text="checkout.product_price"></span>
      </div>
    </div>
  </template-if>

  <!-- Shopify-style cart -->
  <template-if data-condition="is_cart" data-frontend-template="true">
    <template-foreach data-each="item in cartItems" data-frontend-template="true">
      <div class="dt-co-prod-row">
        <div class="dt-co-prod-img-wrap">
          <template-if data-condition="item.image" data-frontend-template="true">
            <img ef-src="item.image" alt="[[ item.name ]]" />
          </template-if>
          <template-else data-frontend-template="true">
            <span class="dt-co-prod-img-ph"><!-- placeholder icon --></span>
          </template-else>
          <span class="dt-co-prod-qty" ef-text="item.quantity">1</span>
        </div>
        <div class="dt-co-prod-info">
          <p class="dt-co-prod-name"><span ef-text="item.name">Product</span></p>
          <div class="dt-co-qty-ctrl">
            <button type="button" data-cart-qty-minus data-code="[[ item.code ]]" data-disable-when-one aria-label="Decrease">&minus;</button>
            <span ef-text="item.quantity">1</span>
            <button type="button" data-cart-qty-plus data-code="[[ item.code ]]" aria-label="Increase">+</button>
          </div>
          <template-if data-condition="cartItems.length > 1" data-frontend-template="true">
            <button type="button" data-cart-qty-remove data-code="[[ item.code ]]" class="dt-co-prod-remove">Remove</button>
          </template-if>
        </div>
        <div class="dt-co-prod-price">
          <span ef-text="item.total"></span>
        </div>
      </div>
    </template-foreach>
  </template-if>
</div>
```

<Warning>
  Do **not** read `cartItems[0]` inside the single-product block — use the `checkout.product_*` keys. In single-product mode `cartItems` is not the source of truth.
</Warning>

***

## Step 3 — subscription vs one-time (conditional)

**Key idea:** the same checkout page serves both one-time and subscription products, because the `?p=` code decides. So every subscription-specific element must be **gated** — never assume a subscription. Gate on the `checkout.subscription` object (it is `null` for one-time products, so it is falsy):

* `<template-if data-condition="checkout.subscription">` — subscription framing (recurring heading, billing note, "save vs one-time", "Subscribe" CTA).
* `<template-if data-condition="!checkout.subscription">` — one-time order framing.

```html theme={null}
<template-if data-condition="checkout.subscription" data-frontend-template="true">
  <h2>Start your subscription</h2>
</template-if>
<template-if data-condition="!checkout.subscription" data-frontend-template="true">
  <h2>Complete your one-time order</h2>
</template-if>
```

### The billing note (four cases)

Subscription products differ in how the first charge works, so the recurring note has to cover four mutually-exclusive cases. This is the production block verbatim — it reads `checkout.subscription.{intro_offer, first_charge_free, trial_days, frequency, frequency_unit}` and formats money with `formatPrice(...)` and values with `[[ … ]]`:

```html theme={null}
<template-if data-condition="checkout.subscription" data-frontend-template="true">
  <span class="subscription-billing-note">
    <!-- 1. Intro offer: N-period intro, then recurring price every cycle -->
    <template-if data-condition="checkout.subscription.intro_offer" data-frontend-template="true">[[ checkout.subscription.intro_offer.period ]]-[[ checkout.subscription.intro_offer.period_unit ]] intro &middot; Then [[ formatPrice(checkout.subscription.intro_offer.recurring_price) ]] every [[ checkout.subscription.frequency ]] [[ checkout.subscription.frequency_unit == 'month' ? (checkout.subscription.frequency > 1 ? 'months' : 'month') : checkout.subscription.frequency_unit ]]</template-if>

    <!-- 2. First charge free -->
    <template-if data-condition="!checkout.subscription.intro_offer && checkout.subscription.first_charge_free" data-frontend-template="true">Try free &middot; Then billed every [[ checkout.subscription.frequency ]] [[ checkout.subscription.frequency_unit == 'month' ? (checkout.subscription.frequency > 1 ? 'months' : 'month') : checkout.subscription.frequency_unit ]]</template-if>

    <!-- 3. Trial days -->
    <template-if data-condition="!checkout.subscription.intro_offer && !checkout.subscription.first_charge_free && checkout.subscription.trial_days > 0" data-frontend-template="true">[[ checkout.subscription.trial_days ]]-day trial &middot; Then billed every [[ checkout.subscription.frequency ]] [[ checkout.subscription.frequency_unit == 'month' ? (checkout.subscription.frequency > 1 ? 'months' : 'month') : checkout.subscription.frequency_unit ]]</template-if>

    <!-- 4. Plain recurring -->
    <template-if data-condition="!checkout.subscription.intro_offer && !checkout.subscription.first_charge_free && checkout.subscription.trial_days == 0" data-frontend-template="true">Billed every [[ checkout.subscription.frequency ]] [[ checkout.subscription.frequency_unit == 'month' ? (checkout.subscription.frequency > 1 ? 'months' : 'month') : checkout.subscription.frequency_unit ]]</template-if>
  </span>
</template-if>
```

| Case | Condition | Note shown |
| - | - | - |
| Intro offer | `checkout.subscription.intro_offer` truthy | `2-week intro · Then $29.00 every month` |
| First charge free | `first_charge_free` and no intro | `Try free · Then billed every month` |
| Trial days | `trial_days > 0` and no intro/free | `14-day trial · Then billed every month` |
| Plain recurring | none of the above | `Billed every 3 months` |

`checkout.subscription.intro_offer.recurring_price` is the price charged **after** the intro ends. The `frequency_unit == 'month' ? …` ternary just pluralizes "month/months"; other units (`day`, `week`, `year`) are printed as-is. For the full subscription scope shape (`price_steps`, `prepaid`, `tiers`), see [Frontend Template Engine: Checkout](/frontend-template-engine/checkout#subscription-products).

<Note>
  In **cart mode** subscription data lives on each line (`item.is_subscription`, `item.subscription`), not on `checkout.subscription`.
</Note>

***

## Step 4 — wallets (Apple Pay / Google Pay)

Place a `<checkout-wallet>` tag where you want the express buttons. The runtime swaps it for an `ef-wallet-standalone` container holding `#applePay` and `#googlePay`, and the client injects whichever wallet the device supports:

```html theme={null}
<checkout-wallet wallets="applePay,googlePay"/>

<template-if data-condition="checkout.wallet_visible" data-frontend-template="true">
  <div class="ef-wallet-divider">
    <div class="ef-wallet-divider-line"></div>
    <span class="ef-wallet-divider-text">or pay another way</span>
    <div class="ef-wallet-divider-line"></div>
  </div>
</template-if>
```

<Warning>
  The `wallets` value is **camelCase**: `wallets="applePay,googlePay"`. The value is passed through verbatim as `data-wallets` and matched against the payment library's wallet identifiers (e.g. Stripe's `disableWallets`), which are camelCase. Snake\_case `apple_pay,google_pay` is **wrong** — it is emitted unchanged, matches nothing, and silently fails to filter wallets. `wallets` and `force` are plain attributes, **not** `data-` prefixed, and `<checkout-wallet>` may be self-closing.
</Warning>

Notes on behavior:

* **Buttons appear automatically** when the device/browser supports a wallet — you do not render them yourself.
* **`checkout.wallet_visible`** flips `false → true` only once a wallet button actually renders (it is promoted, never reset). Gate the "or pay another way" divider on it so the divider never shows above an empty space. Add `force="true"` to pre-render the native Apple Pay button on iOS and set `wallet_visible` immediately, avoiding a first-paint layout shift.
* **Billing address comes from the wallet.** When a customer pays with Apple/Google Pay, the correct billing address is taken from the wallet sheet — no extra fields needed in your template.

For a wallet-first layout, put `<checkout-wallet force="true" wallets="applePay,googlePay"/>` at the top and disable the card panel's own wallet tab with `data-applepay="false"` (next step).

***

## Step 5 — the card panel

Drop in a single `<checkout-cc-panel>` tag. **Do not hand-build card inputs** — the runtime swaps this tag for a gateway-specific secure card form resolved from the domain's merchant:

```html theme={null}
<checkout-cc-panel data-accepted-cards="visa,mastercard,amex,discover" data-applepay="false"></checkout-cc-panel>
<div data-checkout-message></div>
```

What happens:

* Server-side, the tag is replaced with `<div class="checkout-cc-panel" data-gateway="{stripe|nmi|authorize_net}" data-accepted-cards="…">`. The gateway is resolved from the merchant assigned to the domain.
* Client-side, the secure card fields for that gateway are injected (Stripe Elements, NMI CollectJS, or Authorize.Net Accept.js). A resolved merchant/gateway is required for real tokenization.
* `data-accepted-cards` sets the accepted card brands; `data-applepay="false"` suppresses the panel's built-in wallet tab (use it when you place `<checkout-wallet>` separately).

| Attribute | Purpose |
| - | - |
| `data-accepted-cards` | Comma list of brands, e.g. `visa,mastercard,amex,discover` |
| `data-applepay` | `"false"` hides the panel's own wallet tab |
| `data-paypal` | ID of a PayPal merchant: adds a **PayPal** tab next to the card form |
| `data-klarna` | ID of a Klarna merchant: adds a **Klarna** tab next to the card form |

### Adding PayPal

PayPal is a tab inside the same panel, not a separate form. Give the panel your PayPal merchant's ID:

```html theme={null}
<checkout-cc-panel data-accepted-cards="visa,mastercard,amex,discover" data-applepay="false" data-paypal="171"></checkout-cc-panel>
<div data-checkout-message></div>
```

The panel renders **Credit Card** and **PayPal** as tabs, and the same `[data-checkout-submit]` button pays with whichever the buyer picked. With PayPal, the buyer is sent to PayPal to approve and returns to the next funnel step. The customer fields, bumps and totals need no changes. Setup, vaulting for one-click upsells and subscriptions, and sandbox testing are covered in [PayPal](/merchants/paypal).

<Note>
  The card form always comes from the **domain's** merchant, which must be a card gateway (Stripe, NMI, Authorize.Net). PayPal and Klarna cannot be a domain's merchant; they are only ever added this way.
</Note>

<Warning>
  `<checkout-cc-panel>` **requires an explicit closing tag.** Written self-closing (`<checkout-cc-panel/>`) it is neither expanded nor stripped and passes through to the browser as inert markup. (Only `<checkout-wallet>` / `<checkout-apple-pay>` may self-close.) Any children you write inside the panel are discarded.
</Warning>

***

## Step 6 — mark client-side blocks with `data-frontend-template="true"`

Add **`data-frontend-template="true"`** to **every** `template-if`, `template-else`, and `template-foreach` whose condition depends on data that is only known in the browser: the wallet divider, subscription blocks, order bumps, cart items, coupon state, and any `bump.added` / `checkout.wallet_visible` conditional.

**Why:** the server template pass and the client template pass are separate. Values like `checkout.wallet_visible` (true only after a wallet renders), `bump.added` (toggled by the shopper), and coupon state (applied after an async validation) do not exist during the server pass. Marking a block `data-frontend-template="true"` tells the server pass to **leave it alone** and hands it to the client engine, which evaluates it against the live scope. Without the flag, the server tries to evaluate the condition against empty scope and the block is dropped or renders wrong.

```html theme={null}
<!-- Evaluated in the browser, against live scope -->
<template-if data-condition="checkout.wallet_visible" data-frontend-template="true"> … </template-if>
<template-foreach data-each="item in cartItems" data-frontend-template="true"> … </template-foreach>
```

Server-side conditionals that depend on the request (e.g. Blade-style `@if(query.p == 'your-product-4-weeks')`) are the opposite case - those are evaluated during the render and do **not** take the attribute.

<Note>
  Pair client-side blocks with `data-ef-cloak` (and the CSS `[data-ef-cloak] { display: none !important; }`) on anything that would flash before the engine runs. Also hide the raw `template-if` / `template-foreach` tags with `display: none !important` so unprocessed markup never flashes.
</Note>

***

## Step 7 — order bumps

Bumps come from `checkout.bump_products` — an array with per-bump `code`, `name`, `description`, `price` (formatted), `price_raw`, `image`, `added`, and `added_message`. Loop it and render an **offer** state (`!bump.added`) and an **added** state (`bump.added`). Toggling with `@click="bump.added = true/false"` mutates the scope and re-renders:

```html theme={null}
<template-if data-condition="checkout.bump_products.length > 0">
  <template-foreach data-each="bump in checkout.bump_products" data-frontend-template="true">
    <!-- Offer state -->
    <template-if data-condition="!bump.added" data-frontend-template="true">
      <div class="dt-co-bump">
        <div class="flex justify-between gap-2 items-start mb-1">
          <span ef-text="bump.name">Add-on</span>
          <span ef-text="bump.price"></span>
        </div>
        <div data-ef-cloak>
          <p ef-text="bump.description"></p>
          <button type="button" @click="bump.added = true" class="dt-co-add-bump">Click to add to order</button>
        </div>
      </div>
    </template-if>
    <!-- Added state -->
    <template-else data-frontend-template="true">
      <div class="dt-co-bump-applied">
        <span ef-text="bump.name">Add-on</span>
        <span ef-text="bump.price"></span>
        <span ef-text="bump.added_message != '' ? bump.added_message : 'Added to your order'">Added to your order</span>
        <button type="button" @click="bump.added = false" class="dt-co-remove-bump">Remove</button>
      </div>
    </template-else>
  </template-foreach>
</template-if>
```

Added bumps also feed the totals — loop them again in the price summary, filtered to `bump.added`:

```html theme={null}
<template-foreach data-each="bump in checkout.bump_products" data-frontend-template="true">
  <template-if data-condition="bump.added" data-frontend-template="true">
    <div class="dt-co-price-row">
      <span ef-text="bump.name"></span>
      <span ef-text="bump.price"></span>
    </div>
  </template-if>
</template-foreach>
```

### Placing a specific bump in a specific location

The loop above renders **every** bump in one place, in payload order. Most real checkouts want the opposite: a small shipping-protection checkbox tucked under the shipping fields, and a large product-bundle card in the sidebar - each styled differently.

There is **no "get bump by code" lookup**. The idiom is to loop `checkout.bump_products` as usual and filter *inside* the loop on `bump.code`. Because the loop renders nothing when the condition never matches, you can repeat this block as many times as you like, anywhere on the page, and each bump lands in its own slot:

```html theme={null}
<template-foreach data-each="bump in checkout.bump_products" data-frontend-template="true">
  <template-if data-condition="bump.code == 'YOUR-BUMP-CODE'" data-frontend-template="true">
    <!-- everything for this one bump goes here -->
  </template-if>
</template-foreach>
```

That gives three nested levels - `foreach` → code filter → added/not-added - and **every one of them needs `data-frontend-template="true"`**. A missing flag on any level drops the block during the server pass.

#### Example A - compact checkbox bump, next to the shipping fields

```html theme={null}
<template-foreach data-each="bump in checkout.bump_products" data-frontend-template="true">
  <template-if data-condition="bump.code == 'BUMP-SHIPPING-PROTECTION'" data-frontend-template="true">

    <!-- Offer state -->
    <template-if data-condition="!bump.added" data-frontend-template="true">
      <div class="bump-mini bump-mini--unadded">
        <label class="bump-mini-label">
          <input type="checkbox" class="bump-mini-checkbox"
                 @change="bump.added = $event.target.checked">
          <div class="bump-mini-content">
            <div class="bump-mini-top">
              <span class="bump-mini-name" ef-text="bump.name">BUMP NAME</span>
              <span class="bump-mini-price" ef-text="bump.price">BUMP PRICE</span>
            </div>
            <div class="bump-mini-desc" ef-text="bump.description" data-ef-cloak>Bump description</div>
          </div>
        </label>
      </div>
    </template-if>

    <!-- Added state -->
    <template-else data-frontend-template="true">
      <div class="bump-mini bump-mini--added">
        <label class="bump-mini-label">
          <span class="bump-mini-check">&#10003;</span>
          <div class="bump-mini-content">
            <div class="bump-mini-top">
              <span class="bump-mini-name" ef-text="bump.name">BUMP NAME</span>
              <span class="bump-mini-price" ef-text="bump.price">BUMP PRICE</span>
            </div>
            <div class="bump-mini-desc" ef-text="bump.description" data-ef-cloak>Bump description</div>
          </div>
        </label>
        <button type="button" @click="bump.added = false" class="bump-mini-remove">Remove</button>
      </div>
    </template-else>

  </template-if>
</template-foreach>
```

<Note>
  **Checkbox toggling.** `@change="bump.added = $event.target.checked"` works because the event scope exposes `$event` (and `$el` / `$target`) alongside the loop variable. `@change` and `@input` take the same alias families as `@click` (`data-ef-on:change`, `data-ef-on-change`, `data-ef-change`).

  This example is safe without `:checked` because the checkbox only exists in the `!bump.added` branch, so it always renders unchecked. If you collapse the two states into **one** block instead, bind the state explicitly: `<input type="checkbox" :checked="bump.added" @change="bump.added = $event.target.checked">`.
</Note>

#### Example B - rich product card, in its own container

Same filter, different bump code, different markup and placement - this one sits in a dedicated wrapper so CSS can float it beside the summary:

```html theme={null}
<div class="bump-card-wrap bump-card-wrap--desktop-left">
  <template-foreach data-each="bump in checkout.bump_products" data-frontend-template="true">
    <template-if data-condition="bump.code == 'BUMP-BUNDLE'" data-frontend-template="true">

      <template-if data-condition="!bump.added" data-frontend-template="true">
        <div class="bump-card">
          <div class="bump-card-label">
            <span>Complete Your Bundle</span>
            <span class="bump-card-price" ef-text="bump.price">$0.00</span>
          </div>
          <div class="bump-card-body">
            <img ef-src="bump.image" alt="" class="bump-card-img">
            <div class="bump-card-info">
              <div class="bump-card-heading">Add all three and save</div>
              <ul class="bump-card-claims">
                <li>1&times; First product in the bundle</li>
                <li>1&times; Second product in the bundle</li>
                <li>1&times; Third product in the bundle</li>
              </ul>
            </div>
          </div>
          <button type="button" @click="bump.added = true" class="bump-card-btn">+ Add to My Order</button>
        </div>
      </template-if>

      <template-else data-frontend-template="true">
        <div class="bump-card bump-card--added">
          <div class="bump-card-label">
            <span><span class="bump-card-check">&#10003;</span> Added to your order</span>
            <span class="bump-card-price" ef-text="bump.price">$0.00</span>
          </div>
          <!-- …same body… -->
          <button type="button" @click="bump.added = false" class="bump-card-remove">Remove</button>
        </div>
      </template-else>

    </template-if>
  </template-foreach>
</div>
```

<Note>
  **The payload only carries `code`, `name`, `description`, `price`, `price_raw`, `image`, `added` and `added_message`.** Anything richer - the claims list, a bespoke heading, a hero image at a specific size - is hard-coded in the template, as above. Use `ef-text` / `ef-src` for the fields that come from the bump so price, name and image stay in sync with the **Set Checkout Bumps** node, and hard-code only the copy the node cannot supply.
</Note>

#### The totals loop stays unfiltered

Wherever the bump was rendered, the price summary uses the same single loop over all bumps, filtered only on `bump.added`. Nothing there needs to know about placement or codes:

```html theme={null}
<template-foreach data-each="bump in checkout.bump_products" data-frontend-template="true">
  <template-if data-condition="bump.added" data-frontend-template="true">
    <div class="price-breakdown-row">
      <span ef-text="bump.name">Bump</span>
      <span ef-text="bump.price">$0.00</span>
    </div>
  </template-if>
</template-foreach>
```

Ticking the checkbox in Example A mutates `bump.added`, which re-renders the block into its added state, adds the row above, and rolls the bump price into `checkout.subtotal` and `checkout.total` - one state change, three places updated, no extra wiring.

<Warning>
  **A hard-coded `bump.code` is a contract with the funnel's Set Checkout Bumps node.** If that node stops supplying the code - renamed product, edited node, or a split-test branch that serves a different bump set - the filter simply never matches and **the block renders nothing, silently**. There is no error and no empty slot to notice in review.

  Keep the codes in the template and the node in sync, and when you split-test bump sets, make sure every branch either supplies the codes your template targets or the template also has an unfiltered fallback loop.
</Warning>

### Where bumps come from

`checkout.bump_products` is filled from three sources, which merge. A code named by more than one is offered once:

1. **The page's own backend script**, via `checkout_settings.bumps`. Use this when the page should always offer the same bump. See [checkout\_settings order bumps](/checkouts/checkout-functionality-reference).
2. **The Set Checkout Bumps node** (`set_checkout_bumps`) in the funnel graph, whose `bumps` field is an array of bump objects (`title`, `description`, `price`, `added_message`, product code). The node is only offered when the page is flagged as a checkout page.
3. **The `?bumps=` query parameter**, a comma-separated list of bump product codes. This is how a `/b` buy link carries a bump into the checkout.

<Warning>
  `?bumps=` lives only in that one URL. A visitor who opens the page directly, shares the link, or reloads after the parameter is gone sees no bump. If a page should always offer one, declare it in the backend script or the node instead of relying on the link.
</Warning>

Because a bump set can come from a page-event node, you can **A/B test bump configurations**: place a **Split Test → Traffic Distribution** node in front, and give each branch its own **Set Checkout Bumps** node. Different visitors then get different bumps against the same checkout template, and the split test measures which set converts better. See [Page event nodes → Set Checkout Bumps](/funnels/page-events-nodes#set-checkout-bumps) and [Split testing](/funnels/split-testing).

### `bumps` offers, `selected_bumps` chooses

The two query parameters do different jobs, and confusing them loses the offer:

* **`bumps`** is the **offer** list: which bumps the checkout renders at all.
* **`selected_bumps`** is the shopper's **choice** among them, and is what the page writes back to the URL as they tick and untick. When it is present it also decides which boxes start ticked, so an empty `selected_bumps=` means "everything was unticked" and survives a refresh.

Never rewrite `bumps` from the current selection. That deletes the offer the moment nothing is ticked, and the next reload renders no bump at all.

***

## Step 8 — the formless submit

**Checkout submission is not a form submit.** The `<form>` in the examples is only for autofill/semantics (`onsubmit="return false;"`); the runtime sets its form reference to `null` and collects every bound field from the page wrapper instead. Submission is a **click** on a `[data-checkout-submit]` button that `preventDefault()`s and posts via fetch — so fields do **not** have to live inside the `<form>`, and `method="POST"` has no effect.

Wire it with three attributes:

* **`data-template-value="checkout.customer.{field}"`** on each input/select — binds it into the checkout payload (`email`, `phone`, `shipping_address`, `shipping_city`, `shipping_state`, `shipping_zip`, `billing_*`, …).
* **`data-checkout-error="{field}"`** on an empty element — the validation adapter fills it with that field's error message.
* **`data-checkout-message`** on one element — the general status/error line for the whole submit.
* **`data-checkout-submit`** on the pay button (`type="button"`).

```html theme={null}
<form id="quiz-checkout-form" autocomplete="on" onsubmit="return false;">

  <checkout-wallet wallets="applePay,googlePay"/>

  <div class="ef-floating-label-group">
    <input type="email" name="email" data-template-value="checkout.customer.email"
           autocomplete="email" placeholder=" " required />
    <label>Email address</label>
    <div class="ef-form-error" data-checkout-error="email"></div>
  </div>

  <checkout-cc-panel data-accepted-cards="visa,mastercard,amex,discover" data-applepay="false"></checkout-cc-panel>
  <div data-checkout-message></div>

  <button type="button" data-checkout-submit class="dt-co-submit">Purchase</button>
</form>
```

### Backend config: `checkout_settings`

Checkout options are set in a `<script scope="backend">` block via **`setVariable("checkout_settings", { … })`**. This is the production block:

```html theme={null}
<script scope="backend">
setVariable("checkout_settings", {
    collect_tax: false
});
</script>
```

The published object is read by both the render (to build the rendered dropdowns and labels) and `process-checkout` (to enforce the same rules on submit). It sits alongside `checkout_product` / `checkout_cart` (Step 1b) in the same backend block: one names *what* the page sells, the other configures *how* it takes payment.

<Warning>
  **`setVariable` is not optional, and assigning the object is not the same thing.** Backend scripts run in a sandbox, and only what you pass to `setVariable` leaves it. A block that just writes `var checkout_settings = {...}` publishes nothing. It throws no error and the page still renders, so the failure is silent: the country allowlist is not applied and declared bumps never appear. If you build the object in steps, finish with `setVariable("checkout_settings", checkout_settings)`.
</Warning>

Common keys:

| Setting | Purpose |
| - | - |
| `checkout_settings.collect_tax` | Toggle tax collection |
| `checkout_settings.countries` | Restrict the country dropdown, e.g. `['US','CA','GB','AU']` |
| `checkout_settings.usStates` | Restrict the US state dropdown, e.g. `['CA','TX','FL']` |
| `checkout_settings.bumps` | Order bumps this page always offers, e.g. `['bump-shipping-protection']` |
| `checkout_settings.billing_fields` | Which fields the card panel's auto-billing block shows (`['country','zip']`); exposed as `checkout.panel_billing_fields` |
| `checkout_settings.abuse_protection` | Card-testing / velocity protection |
| `checkout_settings.wallet.recurring_description` | What recurs, shown on the Apple Pay sheet |
| `checkout_settings.wallet.recurring_label` | Line item label on the Apple Pay sheet |
| `checkout_settings.wallet.management_url` | Where the buyer manages or cancels the subscription, shown by Apple |

Full semantics: [Checkout functionality reference → `checkout_settings`](/checkouts/checkout-functionality-reference#4-checkout_settings-backend-script).

***

## Output bindings reference

Two ways to print scope values, used throughout the examples above:

| Binding | Use | Example |
| - | - | - |
| `ef-text="expr"` | Set an element's text | `<span ef-text="checkout.product_title">Product</span>` |
| `ef-src="expr"` | Set an `<img>` `src` | `<img ef-src="checkout.product_image" />` |
| `ef-alt="expr"` | Set an `<img>` `alt` | `<img ef-alt="checkout.product_title" />` |
| `[[ expr ]]` | Interpolate inside text/attributes | `alt="[[ item.name ]]"`, `data-code="[[ item.code ]]"` |

Use `[[ … ]]` where you need a value **inside** an attribute or mixed with other text (`data-code="[[ item.code ]]"`); use `ef-text` / `ef-src` / `ef-alt` for a whole element's text or image. `formatPrice(raw)` formats a raw number as currency.

`<template-foreach>` also drives select dropdowns for country/state, each option `{ value, label }`:

```html theme={null}
<select name="shipping_state" data-template-value="checkout.customer.shipping_state">
  <option value="">Select State</option>
  <template-foreach data-each="opt in checkout.usStates">
    <option value="[[ opt.value ]]">[[ opt.label ]]</option>
  </template-foreach>
</select>
```

***

## Page builder vs code editor

Everything above is code-editor HTML. In the **page builder**, use the **Checkout** block category, which maps to the same tags/bindings:

* **Checkout Details** — contact + shipping + billing fields
* **Credit Card Form** — `<checkout-cc-panel>`
* **Checkout Button** — `<button data-checkout-submit>`
* **Price Summary** — totals section
* **Checkout Coupon** — coupon input with apply/clear (`data-apply-coupon`, `data-clear-coupon`)
* **Checkout Bumps** — order bumps
* **Single Product Summary** / **Cart Products** — the `is_single_product` / `is_cart` blocks

For a wallet-first layout, add a `<checkout-wallet force="true" wallets="applePay,googlePay"/>` custom-code block above **Checkout Details** and set `data-applepay="false"` on the **Credit Card Form**.

***

## Related docs

* [Checkout functionality reference](/checkouts/checkout-functionality-reference) — scope keys, `checkout_settings`, abuse protection, submit flow
* [Frontend Template Engine: Checkout](/frontend-template-engine/checkout) — `checkout.*` bindings, totals, subscription shape
* [Apple Pay and Google Pay](/merchants/apple-pay-google-pay) — wallet setup
* [Shopify Checkout](/merchants/shopify-checkout) — where `is_cart` carts come from
* [Buy links](/products/buy-links) — building the `?p=` link
* [Backend scripts: actions](/backend-scripts/actions) - `setVariable` and the rest of the `<script scope="backend">` surface used in Step 1b
* [Set Checkout Bumps node](/funnels/page-events-nodes#set-checkout-bumps) and [Split testing](/funnels/split-testing) — configuring / A/B-testing bumps
* [Checkout redirect behavior](/funnels/checkout-redirect-behavior) — post-checkout routing


# How to set up a new merchant
Source: https://docs.elasticfunnels.io/guides/how-to-set-up-a-new-merchant

Create a merchant, assign it to a domain, map product IDs, and connect funnels

This guide walks you through publishing an offer with a new merchant end-to-end. The flow is the same for all supported merchants (Buygoods, ClickBank, Digistore24, Shopify Checkout, Shop Pay). Platform-specific extras are linked where needed.

<Warning>
  A domain can have only one merchant assigned at a time. Changing a domain's merchant affects all auto-generated buy links on that domain.
</Warning>

## Step 1: Create the merchant

1. Go to **Settings** → **Merchants**
2. Click **Add Merchant**
3. Select a **Gateway** (e.g., Buygoods, ClickBank, Digistore24)
4. Enter your **Account ID** (as required by the gateway)
5. Optional toggles:
   * **Sync Affiliates Locally**: Keep affiliate data mirrored in your account
   * **Use Direct Links**: Use gateway-provided direct links when supported
6. Click **Save**

<Note>
  For ClickBank merchants, you must also create a Pitch Flow in ClickBank. See [ClickBank Merchant Setup](/merchants/clickbank#step-3-set-up-clickbank-pitch-flow). For Shopify Checkout or Shop Pay, see [Shopify Checkout](/merchants/shopify-checkout) and [Shop Pay](/merchants/shop-pay) for setup and product mapping.
</Note>

## Step 2: Assign the merchant to a domain

1. Go to **Settings** → **Domains**
2. Edit the target domain
3. Choose your new merchant in **Merchant**
4. Save

This assignment makes the domain use that merchant for checkout and postbacks.

## Step 3: Map products to the merchant

1. Go to **Settings** → **Products**
2. Open a product and go to the **Merchant information** tab
3. Enter the platform-specific Product ID (e.g., Buygoods product ID, ClickBank product ID)
4. Click **Save**

<Note>
  Product mapping is one-merchant-per-product. Repeat for each product you plan to sell with this merchant.
</Note>

## Step 4: Connect or create your funnel

You have two options:

* Assign an existing funnel to the domain and (optionally) set it as the default funnel.
* Or create a new funnel for this domain.

See:

* [Create Funnel](/funnels/create-funnel)
* [Checkout Redirect Behavior](/funnels/checkout-redirect-behavior)

If you have multiple funnels on the same domain, copy the funnel link from the funnel list. This adds the `?f={funnel_code}` parameter to ensure the correct funnel runs.

## Step 5: Use adaptive purchase links

Use editor tags so links adapt automatically to the current domain's merchant and your product mapping:

* `[BUY=product_code]`
* `[UPSELL=product_code]`
* `[DOWNSELL=product_code]`

These automatically resolve to the correct gateway links for the assigned merchant on the active domain.

<Warning>
  Hardcoded external checkout URLs (e.g., pasted Buygoods/ClickBank links) will not be adapted. Use the tags above instead. See [Buy Links](/products/buy-links) and [Advanced Purchase Links](/products/advanced-purchase-links).
</Warning>

## Testing and debugging

1. Test buy links on the assigned domain and confirm the correct checkout gateway opens
2. Complete a test purchase and verify the intended funnel flow executes
3. Open the **Debug Window** with `Ctrl + Shift + F12` to inspect domain, funnel, and merchant resolution
4. Verify postbacks and analytics update as expected

### Postback setup and validation

Use the **Setup** modal from the **Merchants** list for gateway-specific postback instructions and your unique URL. After you configure the postback in the merchant platform (Buygoods, ClickBank, Digistore24) and trigger a test event, the modal automatically updates to show validation status when the webhook is received.

Recommended ways to trigger validation:

* Use the merchant's built-in "Send Test" feature (where available)
* Or perform a low-value test purchase

### Quick checklist

* [ ] Merchant created in **Settings** → **Merchants**
* [ ] Domain assigned to the merchant in **Settings** → **Domains**
* [ ] Each product mapped in the product's **Merchant information** tab
* [ ] Funnel associated with the domain; default set if desired
* [ ] Links use `[BUY]`, `[UPSELL]`, or `[DOWNSELL]` tags (not hardcoded URLs)
* [ ] Test purchase completes and the correct flow runs

<Note>
  If you add new pages for a specific funnel or merchant, make sure they are added to the funnel flow. Otherwise, they might not trigger the customer flow.
</Note>

## Related documentation

* [ClickBank Merchant Setup](/merchants/clickbank)
* [Buy Links](/products/buy-links)
* [Advanced Purchase Links](/products/advanced-purchase-links)
* [Create Funnel](/funnels/create-funnel)
* [Checkout Redirect Behavior](/funnels/checkout-redirect-behavior)


# Introduction
Source: https://docs.elasticfunnels.io/index

Docs for building funnels, pages, tracking, payments, and integrations in ElasticFunnels

## Start here

Use these docs to build funnels, create pages, connect payments, track campaigns, and debug what happens after a visitor clicks.

<CardGroup>
  <Card title="Create Funnels" icon="rocket" href="/funnels/create-funnel">
    Learn how to create your first funnel from scratch and organize your funnel workflow
  </Card>

  <Card title="Split Testing" icon="flask" href="/funnels/split-testing">
    Test different versions of headlines, videos, and content to optimize conversions
  </Card>

  <Card title="Brand Actions & Alerts" href="/essentials/brand-actions">
    Automated suggestions to optimize costs, fix buy links, and improve data quality
  </Card>
</CardGroup>

## Build a funnel stack

Start with the pieces most teams need first: traffic tracking, lead capture, interactions, buy links, and domains.

<CardGroup>
  <Card title="Meta Ads Integration" icon="chart-line" href="/integrations/meta-ads">
    Connect Facebook/Meta Ads to track ad performance and conversions
  </Card>

  <Card title="Lead Capture Forms" icon="clipboard-list" href="/forms/lead-capture">
    Create and integrate lead capture forms to build your email list
  </Card>

  <Card title="Interactions Panel" href="/pages/interactions-panel">
    Add interactive behaviors like clicks, hovers, animations, and custom JavaScript
  </Card>

  <Card title="Buy Links" icon="shopping-cart" href="/products/buy-links">
    Add purchase links to enable direct product sales from your pages
  </Card>

  <Card title="Custom Domains" icon="globe" href="/domains/custom-domains">
    Set up custom domains and SSL certificates for professional branding
  </Card>
</CardGroup>

## Guides

<CardGroup>
  <Card title="How to set up a new merchant" icon="book" href="/guides/how-to-set-up-a-new-merchant">
    Create a merchant, assign a domain, map product IDs, and connect funnels
  </Card>
</CardGroup>

## What to read next

Common starting points:

* **Brand Actions**: Automated alerts and suggestions for cost optimization and data quality
* **Interactive Elements**: Click handlers, hover effects, animations, and custom JavaScript
* **Funnel Creation**: Step-by-step funnel building and page creation
* **Split Testing**: A/B test headlines, videos, and content
* **Lead Generation**: Forms, popups, and data collection strategies
* **E-commerce Integration**: Buy links, upsells, and affiliate tracking
* **Marketing Tools**: Meta Ads, Google Ads, and analytics integration
* **Customization**: Domains, SSL, fonts, colors, and branding

<Note>
  Ready to start building? Jump straight to our [Create Funnel guide](/funnels/create-funnel) for step-by-step instructions on building your first funnel.
</Note>


# Affiliate Tracking
Source: https://docs.elasticfunnels.io/integrations/affiliate-tracking

Automatically capture and track affiliate referral data across platforms

Automatically capturing affiliate data helps you track marketing performance across different platforms.

## How It Works

* Affiliate-network postbacks are received automatically once you've configured the matching merchant or integration
* View stats on your dashboard for each affiliate individually
* Use the Tracking Link Builder to create properly formatted tracking URLs with UTM parameters for accurate attribution

## Supported Networks

ElasticFunnels groups affiliate-network integrations into two patterns:

* **Inbound (we receive)** — Postbacks come **from** the network so EF can record sales, refunds, chargebacks, and rebills. Setup is on the network side: paste the EF postback URL into your network account.
* **Outbound (we send)** — EF posts conversion events **to** the network so it can attribute lander or pre-lander performance. Setup is in EF: enter the network's postback URL plus the relevant click-id parameter.

### Inbound networks (postbacks → ElasticFunnels)

| Network | Auth / validation | Receives | Notes |
| - | - | - | - |
| [BuyGoods](/integrations/buygoods) | Postback URL only | Purchase, refund, cancel, chargeback, commission void | Auto-creates tracking pixels for BuyGoods merchants |
| [ClickBank S2S](/integrations/clickbank) | **Secret key** validation | Purchase, refund, chargeback, upsell | Same secret key you set in the ClickBank backend |
| [JVZoo Affiliate S2S](/integrations/jvzoo) | Postback URL only | Affiliate purchase, refund | Reads `tid` macro to attribute to the original click |
| JVZoo Vendor IPN | **cverify** signature | Sale, rebill, refund, chargeback, cancel | Uses your JVZoo secret key to verify v1/v2 IPNs |
| Digistore24 S2S | Postback URL only | Currently scaffolded only — full postback handling in development | |

### Outbound networks (postbacks ← ElasticFunnels)

| Network | Click-id parameter | What we send |
| - | - | - |
| [Everflow](/integrations/everflow) | `transaction_id` (or `sub1`–`sub5`) | Purchase + macros (order\_id, amount, email, currency, geo, sub1–5) |
| [RedTrack](/integrations/redtrack) | `rtkclickid` / `clickid` (or configured sub) | Purchase, refund, chargeback with `{clickid}`, `{sum}`, `{amount}`, `{currency}`, `{type}` |

<Info>
  **Multiple networks at once.** EF supports running outbound integrations like Everflow and RedTrack alongside inbound networks like BuyGoods or ClickBank. Each conversion fans out to every integration whose merchant filter matches.
</Info>

## Tracking Link Builder

The Tracking Link Builder creates tracking URLs with UTM parameters for attribution across your marketing channels.

### Accessing the Tracking Link Builder

You can access the Tracking Link Builder in several ways:

<AccordionGroup>
  <Accordion title="From Tools Menu">
    1. Navigate to **Tools** in the main menu
    2. Click on the **Tracking** tab
    3. Select **Tracking Link Builder**
  </Accordion>

  <Accordion title="From Pages List">
    1. Go to **Pages** in the main menu
    2. Find the page you want to create a tracking link for
    3. Click the dropdown menu (three dots) on the page row
    4. Select **"Get Tracking Link"**

    The builder will automatically open with the selected page pre-filled.
  </Accordion>

  <Accordion title="From Funnels List">
    1. Go to **Funnels** in the main menu
    2. Find the funnel you want to create a tracking link for
    3. Click the dropdown menu (three dots) on the funnel row
    4. Select **"Get Tracking Link"**

    The builder will automatically open with the selected funnel pre-filled.
  </Accordion>
</AccordionGroup>

### How to Use the Tracking Link Builder

#### Step 1: Select Your Destination

Choose how you want to specify your destination URL:

<CardGroup>
  <Card title="URL Tab" icon="link">
    Enter a custom URL manually. Perfect for external landing pages or specific URLs.
  </Card>

  <Card title="Page Tab" icon="file-text">
    Select an existing page from your ElasticFunnels account. The page URL will be automatically populated.
  </Card>

  <Card title="Funnel Tab" icon="sitemap">
    Select an existing funnel from your account. The funnel URL will be automatically generated.
  </Card>
</CardGroup>

#### Step 2: Choose Your Ad Platform (Optional)

Select an ad platform from the **"Auto Cost Update"** dropdown to automatically populate UTM parameters with the correct format:

* **Meta Ads** - Facebook/Meta advertising campaigns
* **Google Ads** - Google advertising campaigns
* **TikTok Ads** - TikTok advertising campaigns
* **Bing Ads** - Microsoft Bing advertising campaigns
* **LinkedIn Ads** - LinkedIn advertising campaigns

<Info>
  When you select a platform, the UTM parameters are automatically populated with the correct tokens and format for that platform. You can still customize them manually if needed.
</Info>

#### Step 3: Configure UTM Parameters

The builder includes fields for all standard UTM parameters:

* **UTM Source** - The source of your traffic (e.g., "facebook", "google", "email")
* **UTM Medium** - The marketing medium (e.g., "cpc", "email", "social")
* **UTM Campaign** - The campaign name or identifier
* **UTM Term** - Keywords or ad identifiers (often used for ad names)
* **UTM Content** - Additional content identifier (often used for ad set names)

<Warning>
  For proper attribution in Campaigns Management, ensure UTM parameters match your campaign structure:

  * `utm_campaign` = Campaign name
  * `utm_content` = Ad set name
  * `utm_term` = Ad name
</Warning>

#### Step 4: Add Dynamic Tokens

Click the **"Add Token"** button next to any UTM field to insert dynamic tokens that will be replaced by the ad platform:

**Meta Ads Tokens:**

| Token | Description |
| - | - |
| `{{campaign.name}}` | Campaign name |
| `{{adset.name}}` | Ad set name |
| `{{ad.name}}` | Ad name |
| `{{campaign.id}}` | Campaign ID |
| `{{adset.id}}` | Ad set ID |
| `{{ad.id}}` | Ad ID |
| `{{site_source_name}}` | Site source name |
| `{{placement}}` | Ad placement |

**Google Ads Tokens:**

| Token | Description |
| - | - |
| `{campaignid}` | Campaign ID |
| `{keyword}` | Keyword |
| `{creative}` | Creative ID |
| `{adgroupid}` | Ad group ID |
| `{placement}` | Placement |
| `{device}` | Device type |
| `{network}` | Network type |
| `{matchtype}` | Match type |
| `{target}` | Target |

**TikTok Ads Tokens:**

| Token | Description |
| - | - |
| `__CAMPAIGN_NAME__` | Campaign name |
| `__CID_NAME__` | Campaign group name |
| `__AID_NAME__` | Ad name |
| `__CAMPAIGN_ID__` | Campaign ID |
| `__CID__` | Campaign group ID |
| `__AID__` | Ad ID |
| `__PLACEMENT__` | Placement |

**Bing Ads Tokens:**

| Token | Description |
| - | - |
| `{Campaign}` | Campaign name |
| `{CampaignId}` | Campaign ID |
| `{AdGroupName}` | Ad group name |
| `{AdGroupId}` | Ad group ID |
| `{AdTitle}` | Ad title |
| `{AdId}` | Ad ID |
| `{Keyword}` | Keyword |
| `{QueryString}` | Query string |
| `{Device}` | Device type |
| `{MatchType}` | Match type |
| `{Network}` | Network type |

**LinkedIn Ads Tokens:**

| Token | Description |
| - | - |
| `{{CAMPAIGN_NAME}}` | Campaign name |
| `{{CAMPAIGN_ID}}` | Campaign ID |
| `{{CAMPAIGN_GROUP_NAME}}` | Campaign group name |
| `{{CAMPAIGN_GROUP_ID}}` | Campaign group ID |
| `{{CREATIVE_ID}}` | Creative ID |
| `{{ACCOUNT_ID}}` | Account ID |
| `{{ACCOUNT_NAME}}` | Account name |

<Note>
  Tokens are automatically replaced by the ad platform when someone clicks your link. This ensures accurate tracking even if campaign names change.
</Note>

#### Step 5: Copy Your Final Link

Once you've configured all parameters:

1. Review the **Final Link** at the bottom of the builder
2. Click the **"Copy Link"** button to copy it to your clipboard
3. Use this link in your ad campaigns

<Info>
  The final link includes all UTM parameters and the `adid` parameter (automatically added based on your selected platform) for proper attribution and ad spend tracking.
</Info>

### Best Practices for Tracking Links

<Steps>
  <Step title="Use Platform Templates">
    Always select your ad platform to ensure UTM parameters are formatted correctly for that platform's requirements.
  </Step>

  <Step title="Match Campaign Names Exactly">
    Ensure UTM parameter values match your campaign, ad set, and ad names exactly in Meta Ads (or other platforms) for proper attribution.
  </Step>

  <Step title="Use Dynamic Tokens">
    Prefer dynamic tokens (like `{{campaign.name}}`) over static values when possible. This ensures tracking continues to work if you rename campaigns.
  </Step>

  <Step title="Test Your Links">
    After creating a tracking link, test it by clicking it and verifying the UTM parameters appear correctly in your analytics.
  </Step>

  <Step title="Keep Links Organized">
    Use consistent naming conventions in your UTM parameters to make reporting and analysis easier.
  </Step>
</Steps>

## Viewing Affiliate Data

1. Go to your main dashboard
2. Navigate to the "Analytics" or "Affiliates" section
3. Select individual affiliates to see their performance metrics
4. Filter by date ranges, products, or traffic sources

## Key Metrics Tracked

* **Clicks**: Number of visitors from each affiliate
* **Conversions**: Sales generated by each affiliate
* **Revenue**: Total revenue attributed to each affiliate
* **Conversion Rate**: Percentage of clicks that convert
* **Average Order Value**: Average purchase amount per affiliate

## Integration with Campaigns Management

Tracking links created with the Tracking Link Builder work with Campaigns Management:

* **Proper Attribution**: UTM parameters ensure conversions are correctly attributed to campaigns, ad sets, and ads
* **Funnel Analytics**: When UTM parameters match your campaign structure, you'll see funnel metrics (revenue, sales, profit) in Campaigns Management
* **Ad Spend Tracking**: The `adid` parameter enables automatic ad spend tracking and ROI calculations

<Info>
  For detailed information about managing campaigns and viewing unified metrics, see the [Campaigns Management](/integrations/campaigns-management) documentation.
</Info>

## Best Practices

* Regularly review affiliate performance data
* Identify your top-performing affiliates for special promotions
* Use data to optimize commission structures
* Provide performance feedback to your affiliate partners
* Set up alerts for significant performance changes
* **Always use the Tracking Link Builder** for creating tracking URLs to ensure proper formatting and attribution
* **Test tracking links** before launching campaigns to verify parameters are working correctly


# AI Providers (BYO key)
Source: https://docs.elasticfunnels.io/integrations/ai-providers

Bring your own OpenAI, Anthropic, or Google Gemini key to power AI generation, page cloning, quizzes, and AI chat features inside ElasticFunnels.

## Overview

ElasticFunnels uses AI for several features — page generation, page cloning, copy rewriting, AI chat, quiz building, split-test analysis, and on-page interaction generation. You bring your own API keys for any of these providers, and EF routes each task to the right model.

This is a **bring-your-own-key** integration: you control billing, rate limits, model selection, and which provider you trust for each task.

## Supported providers

<CardGroup>
  <Card title="OpenAI" icon="circle-nodes">
    GPT-4-class and GPT-5-class models, plus reasoning models (o-series). Used for general copywriting, page generation, AI chat, and split-test analysis.
  </Card>

  <Card title="Anthropic Claude" icon="brain">
    Claude 3.5 Sonnet, 3 Opus, 3 Haiku. Used for long-form copy, page cloning, and reasoning-heavy workflows.
  </Card>

  <Card title="Google Gemini" icon="atom">
    Gemini 2.5 Pro, 2.5 Flash, 2.0 Flash. Optimized for page-event generation, script-rule generation, and multimodal page cloning with reference images.
  </Card>
</CardGroup>

## What needs a key

| Feature | Provider used (default) | Notes |
| - | - | - |
| AI page generation | OpenAI or Anthropic | Picks based on prompt length and your default |
| Page cloning from URL | Anthropic or Gemini | Gemini is preferred when reference images are extracted |
| Page cloning with screenshots | Gemini | Multimodal model required |
| AI Assistant inside the page builder | OpenAI | Chat + targeted edits |
| Page event / interaction generation | Gemini 2.5 Flash | Cheap, fast, well-suited to script generation |
| Quiz builder AI | OpenAI | Question + outcome generation |
| Copy rewriting (component panel) | OpenAI | One-shot with the user's style notes |
| Split-test analysis | OpenAI or Anthropic | Reads conversion data and writes a recommendation |
| Email copy assist | OpenAI | Subject + body suggestions |

If a feature needs a provider you haven't connected, the UI shows a "Connect provider" prompt linking back to the integration form.

## Setup

<Steps>
  <Step title="Get an API key">
    * **OpenAI**: [platform.openai.com](https://platform.openai.com) → **API Keys** → **Create new secret key**.
    * **Anthropic**: [console.anthropic.com](https://console.anthropic.com) → **Settings** → **API Keys** → **Create Key**.
    * **Google Gemini**: [aistudio.google.com](https://aistudio.google.com) → **Get API key** → **Create API key in new project**.
  </Step>

  <Step title="Activate the integration in EF">
    Go to **Integrations** → **AI** and click the provider tab.
  </Step>

  <Step title="Paste the key">
    Paste the API key into the form and click **Save**. Keys are encrypted at rest.
  </Step>

  <Step title="(Optional) Override default models">
    Per-feature model overrides live on the integration form. Defaults are sensible — only override if you're cost-tuning or want a specific model family for a particular task.
  </Step>

  <Step title="Test">
    Open any AI surface (the page builder's AI assistant, or **Pages** → **Generate with AI**) and verify the generation runs without authentication errors.
  </Step>
</Steps>

<Tip>
  **Why BYO key?** AI calls can quickly become the largest line item in a SaaS bill. Bringing your own key keeps cost transparent (you see it on your provider invoice) and lets you negotiate enterprise pricing or use credits.
</Tip>

## Cost & rate limits

EF tracks token usage and approximate cost per request inside the AI logs. You can view per-feature spend under **Logs** → **AI Generations**. Rate limits and monthly quotas are enforced by the provider, not EF — adjust them in the provider's dashboard.

## Privacy

* API keys are encrypted at rest and never logged.
* Prompts are only sent to the provider associated with the feature you're using.
* ElasticFunnels does not train any models on your data.
* Whether the provider trains on your prompts is governed by your account settings with that provider — Anthropic and OpenAI both let you opt out at the account level.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication errors">
    Regenerate the key in the provider's dashboard, paste the new value into EF, and save. Old keys may have been revoked.
  </Accordion>

  <Accordion title="Rate-limit errors">
    The provider is throttling your account. Either request a quota increase, or switch to a cheaper / faster model in the integration form (e.g. Gemini 2.5 Flash for page-event generation).
  </Accordion>

  <Accordion title="Generation cuts off mid-output">
    The model hit its max output token limit. Try a longer-context model from the same provider, or break the task into smaller prompts (the AI assistant supports follow-ups).
  </Accordion>
</AccordionGroup>


# Buygoods Integration
Source: https://docs.elasticfunnels.io/integrations/buygoods

Connect Buygoods for affiliate tracking, automated postbacks, and order processing

## Overview

Buygoods integration handles server-to-server (S2S) postbacks from the Buygoods affiliate network. The integration automatically receives order information, creates conversion records, and can be configured as both a payment gateway and fulfillment provider.

## What This Integration Provides

<CardGroup>
  <Card title="Automatic Postbacks" icon="arrow-trend-up">
    Receive and process Buygoods webhook postbacks automatically
  </Card>

  <Card title="Conversion Tracking" icon="chart-line">
    Automatically create conversion records from Buygoods orders
  </Card>

  <Card title="Transaction Types" icon="list">
    Support for purchases, refunds, cancellations, chargebacks, and commission voids
  </Card>

  <Card title="Tracking Pixels" icon="eye">
    Automatically create tracking pixels for Buygoods merchants
  </Card>
</CardGroup>

## Setup Guide

### Step 1: Configure as Merchant

1. Go to **Settings → Merchants**
2. Create or edit a merchant
3. Select **Buygoods** as the payment gateway
4. Configure merchant settings

<Note>This integration is used as an affiliate. To set up Buygoods as a merchant, see [How to set up a new merchant](/guides/how-to-set-up-a-new-merchant).</Note>

### Step 2: Get Postback URLs

1. Go to **Settings → Integrations → Affiliate Networks**
2. Find **Buygoods** and click **"Activate"** or **"Manage"**
3. Copy the **Conversion URL** and **Refund URL** provided
4. These URLs will be used in your Buygoods backoffice

### Step 3: Configure in Buygoods Backoffice

1. Log into your Buygoods affiliate account
2. Navigate to the **postback/tracking section**
3. Add the **conversion URL** for successful purchases
4. Add the **refund URL** for processing refunds
5. Save your settings

<Info>
  The postback URLs are unique to your ElasticFunnels account and will automatically receive postbacks from Buygoods when orders are placed.
</Info>

## Transaction Types

The integration supports multiple transaction types:

<AccordionGroup>
  <Accordion title="Purchase">
    When a customer completes a purchase, Buygoods automatically sends a postback. This creates a purchase conversion in ElasticFunnels.
  </Accordion>

  <Accordion title="Refund">
    When a refund is processed, Buygoods automatically sends a postback. This creates a refund conversion linked to the original purchase.
  </Accordion>

  <Accordion title="Cancel">
    When an order is cancelled, Buygoods automatically sends a postback. This creates a cancel conversion.
  </Accordion>

  <Accordion title="Chargeback">
    When a chargeback occurs, Buygoods automatically sends a postback. This creates a chargeback conversion.
  </Accordion>

  <Accordion title="Commission Void">
    When a commission is voided, Buygoods automatically sends a postback. This is processed separately from order conversions.
  </Accordion>
</AccordionGroup>

<Info>
  Commission notifications are processed separately from order conversions. Only actual order postbacks create conversion records.
</Info>

## Click ID Tracking

### How Click IDs Work

Buygoods uses click tracking to identify which affiliate links led to conversions:

* **Automatic Tracking:** Click information is automatically captured from Buygoods postbacks
* **Validation:** System validates click tracking data and handles any formatting issues
* **Attribution:** Conversions are automatically attributed to the affiliate link that generated the click

### Malformed Click ID Handling

If a click ID contains placeholder characters or is malformed:

* The system automatically detects invalid click IDs
* Conversion is still processed and tracked
* Issues are logged for review

<Info>
  The system automatically handles malformed click IDs to ensure conversions are still tracked even if the click ID format is incorrect.
</Info>

## Conversion Updates

If you need to update an existing conversion (for example, to correct order amounts or customer information), you can configure Buygoods to send an update postback. The system will automatically update the existing conversion instead of creating a new one.

<Info>
  Contact support if you need to update existing conversions. The system handles this automatically when configured properly.
</Info>

## Payment Gateway & Fulfillment Provider

### Payment Gateway Configuration

Buygoods can be configured as a payment gateway:

1. Go to **Settings → Merchants**
2. Edit your merchant
3. Select **Buygoods** as the payment gateway
4. Configure payment settings

### Fulfillment Provider Configuration

Buygoods can also be configured as a fulfillment provider:

1. Go to **Products** in the main menu
2. Edit a product
3. Select **Buygoods** as the fulfillment provider
4. Configure fulfillment settings

<Tip>
  You can use Buygoods as both a payment gateway and fulfillment provider, or use it for just one function depending on your needs.
</Tip>

## Automatic Tracking Pixel Creation

When you configure Buygoods as a merchant:

* Tracking pixels are automatically created
* Pixels track page views and conversions
* Enables accurate attribution for Buygoods orders
* Works with the pixel attribution system

<Info>
  Tracking pixels are created automatically when the merchant is configured. You don't need to manually set them up.
</Info>

## What Gets Tracked

* **Conversion Data**: Automatically receive purchase notifications
* **Commission Tracking**: See your earnings in real-time
* **Refund Processing**: Handle refunds automatically
* **Cancellation Tracking**: Track cancelled orders
* **Chargeback Tracking**: Monitor chargebacks
* **Performance Metrics**: Track your promotional performance
* **Click Attribution**: Track which affiliate links generated conversions

## What Information is Tracked

The integration automatically receives and processes the following information from Buygoods:

* **Order Information:** Order ID, order amount, and transaction details
* **Customer Information:** Customer name and email address
* **Transaction Type:** Purchase, refund, cancellation, chargeback, or commission void
* **Click Tracking:** Information about which affiliate link generated the conversion

## Troubleshooting

<AccordionGroup>
  <Accordion title="No Conversions Appearing">
    **Possible Causes:**

    * Postback URLs not added correctly in Buygoods backoffice
    * Click tracking information not being passed correctly
    * Postback URL format incorrect

    **Solution:**

    1. Verify postback URLs are copied correctly (no extra spaces)
    2. Check that Buygoods links include proper tracking information
    3. Test with a small purchase to verify tracking works
  </Accordion>

  <Accordion title="Click Tracking Issues">
    **Issue:** Conversions not being attributed to the correct affiliate links

    **Solution:**

    * System automatically handles click tracking issues
    * Ensure Buygoods links are formatted correctly
    * Contact support if attribution issues persist
  </Accordion>

  <Accordion title="Refunds Not Processing">
    **Possible Causes:**

    * Refund URL not configured in Buygoods
    * Refund postback not being sent

    **Solution:**

    1. Verify refund URL is added in Buygoods backoffice
    2. Check that refund postbacks are being sent
    3. Allow up to 15 minutes for data to appear
  </Accordion>

  <Accordion title="Conversion Updates Not Working">
    **Issue:** Updates to existing conversions not processing

    **Solution:**

    1. Contact support to verify update postback configuration
    2. Ensure the order ID matches the original conversion
    3. Check that Buygoods is sending update postbacks correctly
  </Accordion>
</AccordionGroup>

## Best Practices

<Steps>
  <Step title="Verify Postback URLs">
    Double-check that postback URLs are copied correctly into Buygoods backoffice. Any typos will prevent postbacks from working.
  </Step>

  <Step title="Test with Small Purchase">
    Test the integration with a small purchase first to verify tracking works before running large campaigns.
  </Step>

  <Step title="Monitor Click IDs">
    Check your conversion data regularly. While the system handles malformed click IDs automatically, it's better to ensure Buygoods links are formatted correctly.
  </Step>

  <Step title="Verify Tracking Pixels">
    Tracking pixels are created automatically when you configure Buygoods as a merchant. Verify they're working by checking your conversion attribution.
  </Step>

  <Step title="Handle All Transaction Types">
    Ensure your Buygoods configuration handles all transaction types (purchases, refunds, cancellations, chargebacks) appropriately.
  </Step>
</Steps>

## Security & Privacy

* Postback URLs are unique to your account
* Click IDs are validated before processing
* Customer data is handled securely
* All transactions are logged for audit purposes

<Info>
  Allow up to 15 minutes for data to appear after a purchase. Postbacks are processed in real-time, but there may be a slight delay.
</Info>

## Next Steps

<CardGroup>
  <Card title="Merchant Setup Guide" icon="store" href="/guides/how-to-set-up-a-new-merchant">
    Learn how to set up Buygoods as a merchant
  </Card>

  <Card title="Analytics Dashboard" icon="chart-mixed" href="/analytics/overview">
    View your conversion and performance data
  </Card>

  <Card title="Clickbank Integration" icon="link" href="/integrations/clickbank">
    Set up Clickbank for additional affiliate tracking
  </Card>

  <Card title="Affiliate Tracking" icon="chart-line" href="/integrations/affiliate-tracking">
    Learn about affiliate tracking and attribution
  </Card>
</CardGroup>


# External Call Center Integrations
Source: https://docs.elasticfunnels.io/integrations/callcenters

Push abandoned cart, sales, failed payment, and subscription-lifecycle events to third-party call center providers

ElasticFunnels integrates with external call center providers to automatically push data for abandoned cart recovery, sales follow-ups, failed payment calls, subscription dunning escalation, cancellation routing, and winback (re-engagement) leads.

<Info>
  These are **outbound data pushes** to third-party providers. If you want to run your **own** call center with agent tools, phone orders, and commission tracking, see the [Call Center Suite](/callcenter/overview).
</Info>

## Supported Providers

<CardGroup>
  <Card title="Organization Callcenter" icon="building">
    Send work to your **own** in-house call center module instead of an external webhook. Creates internal queue items for your agents.
  </Card>

  <Card title="HelpGrid" icon="headphones">
    Full suite: abandoned carts, new sales, failed payments, subscription dunning, cancellations, and winback leads.
  </Card>

  <Card title="Tauk (Listflex)" icon="phone">
    Cart recovery and lead management via the Listflex API. Supports the full event matrix including abandoned carts.
  </Card>

  <Card title="Logicall" icon="phone-volume">
    Full suite: enterprise abandoned-cart recovery plus sales, failed payment, and full subscription-lifecycle support.
  </Card>

  <Card title="SalesBound" icon="chart-line-up">
    Sales follow-ups, failed payments, subscription dunning, cancellation, and winback routing. Does not receive abandoned carts.
  </Card>

  <Card title="Committed Coaches" icon="users">
    High-touch coaching, failed payments, subscription dunning, cancellation, and winback routing. Does not receive abandoned carts.
  </Card>

  <Card title="Nuyu" icon="user-headset">
    Sales, failed payments, subscription dunning, cancellations, and winback. Phone number is **not** required for sales.
  </Card>
</CardGroup>

## What Each Provider Supports

| Event Type | Org. CC | HelpGrid | Tauk | Logicall | SalesBound | Committed Coaches | Nuyu |
| - | - | - | - | - | - | - | - |
| **Abandoned carts** | Yes | Yes | Yes | Yes | — | — | — |
| **New sales** | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Failed payments** | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Subscription renewal failed** | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Subscription cancel** | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Subscription winback** | Yes | Yes | Yes | Yes | Yes | Yes | Yes |

<Info>
  A "Yes" in the matrix only declares **what the provider can technically receive**. Each event still has to be explicitly enabled on your integration — see [Per-Event Configuration](#per-event-configuration) below. By default only **Abandoned carts** is enabled for HelpGrid / Logicall / Tauk. All other events are off until you turn them on.
</Info>

<Info>
  **Committed Coaches** and **Nuyu** are purchase-endpoint providers — subscription events are sent via their sales webhook. **Nuyu** is outbound-only (no incoming postbacks from the provider back to ElasticFunnels).
</Info>

<Tip>
  **Organization Callcenter** is only enabled when an active call center exists for your organization (Settings → Call Center). Use it to keep work in-house; mix and match with external providers per-merchant if needed.
</Tip>

## Common Use Cases

### Abandoned Cart Recovery

When a customer enters their email but doesn't complete the purchase, their data is sent to HelpGrid or Logicall after a short delay. A call center agent can then reach out to help them complete the sale. If the customer comes back and buys within the delay window, the pending abandoned-cart call is **automatically cancelled**.

### New Order Follow-Up

After a successful purchase, order data is sent to SalesBound, Committed Coaches, Nuyu, HelpGrid, or Logicall. Ideal for high-ticket offers where a "welcome call" or "upsell call" is part of the flow.

### Failed Payment Calls

When a first-time charge fails (bad card, fraud decline, AVS mismatch, etc.), the customer data — plus the full decline context — is sent to the provider after a configurable delay. If a successful sale for the same customer lands inside that delay window, the pending call is **automatically cancelled**, so you never call a customer who just recovered themselves.

### Subscription Dunning Escalation

When a subscription renewal fails and the retry count reaches your configured escalation threshold, the failed payment data — including the gateway decline code and message — is sent to providers with subscription support. Agents can call the customer to update their payment method. If the next retry succeeds inside the delay window, the pending call is cancelled.

### Cancellation Routing

When a subscription is cancelled (voluntarily or because dunning was exhausted), the data can be routed to providers for a retention call attempt.

### Winback / Re-engagement

30 days after a subscription cancels, a `subscription_winback` event is fired with the cancel reason, original purchase details, and contact info. Providers can use this as a re-engagement lead ("we miss you, here's X% off to come back").

## Setup

<Steps>
  <Step title="Create the integration">
    Go to **Settings** → **Integrations**. Choose your provider and enter the **Webhook URL** or **API Keys** provided by your call center account manager. Save.
  </Step>

  <Step title="Configure merchant filtering">
    Set the integration to listen to **All Merchants** or a specific **Whitelist**. Use the whitelist if you have different call centers for different products or regions.
  </Step>

  <Step title="Configure per-event behavior">
    In the **Events** table on the integration form, toggle on each event you want the provider to receive and — for failed-payment / subscription-failed events — set a delay and an optional decline-code filter. See [Per-Event Configuration](#per-event-configuration) below.
  </Step>

  <Step title="Enable subscription escalation (optional)">
    Go to **Settings** → **Merchants**, edit your merchant, and open the **Email** tab. In **Dunning Configuration**, set **Callcenter Escalation After Retry #** and enable **Send to Callcenter on Cancel** if needed. These are **merchant-level gates** on top of the per-event integration config — the integration still has to have the corresponding event enabled for anything to be sent.
  </Step>

  <Step title="Test the connection">
    Use the **Test Webhook** button (available for most providers) to send a sample payload and verify the connection is active.
  </Step>
</Steps>

<Tip>
  Always verify your Webhook URL with a test before going live to ensure your data is being captured correctly.
</Tip>

## Per-Event Configuration

Each integration exposes an **Events** table with one row per supported event type. For each row you can configure:

| Option | What it does |
| - | - |
| **Enabled** | Master on/off for this event on this integration. When off, no sends of this event will go to this provider — even if the merchant-level dunning gate fires. |
| **Delay (seconds)** | How long to wait before actually sending the event. Lets counter-events (e.g. a successful sale) cancel the pending call. Default `60` for `abandon` / `failed_payment` / `subscription_failed`; `0` for immediate-fire events (`sale`, `subscription_cancel`, `subscription_winback`). |
| **Decline-code filter** | Only applies to `failed_payment` and `subscription_failed`. A comma-separated list of decline codes combined with a **Whitelist** (only these) or **Blacklist** (skip these) mode. Lets you avoid calling customers whose card was declined for a reason they can't fix (e.g. `do_not_honor` hard fails) or only call for actionable decline reasons. |

## Delays & Auto-Cancellation

Delays are the mechanism that makes the system **self-correcting**. Two high-value cancellation flows happen automatically:

* **Purchase cancels abandoned-cart and failed-payment calls.** If a customer's email or phone matches a pending `abandon` or `failed_payment` call and a successful sale comes in inside the delay window, the pending call is marked `cancelled` and the provider is never contacted.
* **Successful renewal cancels pending subscription-failed calls.** If a `subscription_renewal_failed` was queued for a customer and the next retry succeeds before the delay elapses, the pending call is cancelled.

You can monitor this in the **Logs** section — cancelled dispatches are labelled with the counter-event that triggered the cancellation.

## Decline Code Filtering

For `failed_payment` and `subscription_failed` events, each failed charge is enriched with the full decline context from the gateway:

* `decline_reason` — human-readable reason (e.g. "insufficient funds")
* `decline_code` — gateway-normalized short code (e.g. `insufficient_funds`, `generic_decline`, `lost_card`)
* `error_code` — top-level error class (e.g. `card_declined`)
* `gateway_response_code` / `gateway_response_message` — raw gateway output

Use the **Decline-code filter** on the event row to control which failures reach the call center:

* **Blacklist** (default mode, empty list) — send every decline except the codes you list. Useful for excluding hard fails (`lost_card`, `stolen_card`, `fraudulent`, `do_not_honor`).
* **Whitelist** — only send declines with the codes you list. Useful when you only want to call for specific recoverable reasons (`insufficient_funds`, `expired_card`, `card_declined`).

The exact code values depend on the gateway. Stripe codes are listed in [Stripe's decline\_code docs](https://stripe.com/docs/declines/codes); NMI returns the response text as both `responsetext` and `response_code`.

## Monitoring

You can see all outbound postbacks to your call centers in the **Logs** section of your dashboard. Each dispatch shows:

* Integration + event type
* Scheduled time and actual send time
* Status (`pending`, `sent`, `cancelled`, `failed`)
* If cancelled — which counter-event triggered the cancellation
* If failed — the error response from the provider

<Tip>
  If a `failed_payment` call is never being dispatched, check (in order): (1) the provider's global capability in the matrix above, (2) the **Enabled** toggle for that event on your integration, (3) the decline-code filter mode + list, and (4) the merchant-level **Callcenter Escalation After Retry #** gate if this is a subscription renewal.
</Tip>


# Campaigns Management
Source: https://docs.elasticfunnels.io/integrations/campaigns-management

Manage your ad campaigns, ad sets, and ads directly from ElasticFunnels with unified performance metrics

## Overview

Campaigns Management gives you control over your ad campaigns without leaving ElasticFunnels. View your campaigns, ad sets, and ads in one interface that combines the ad platform's metrics with your funnel's conversion data, giving you a complete picture of ROI and performance.

Open it from **Reports → Ad Campaigns** in the sidebar, then choose which connected integration to view.

### Supported Platforms

| Platform | Hierarchy | Spend metrics | Pause and activate | Budget edits | Creative preview |
| - | - | - | - | - | - |
| Meta Ads | Campaign → ad set → ad | Yes | All three levels | Campaign and ad set | Images and videos |
| Google Ads | Campaign → ad group → ad | Yes | All three levels | Campaign only | Headlines and descriptions |

<Note>
  Most of this guide uses Meta Ads names. Google Ads works the same way, with **ad groups** in place of ad sets. Where the two differ, the difference is called out.
</Note>

<Info>
  Google Ads holds the budget on the campaign, so ad groups have no budget of their own. The ad group rows show the parent campaign's budget for reference. Editing it there is not possible, so change the campaign budget instead.
</Info>

## What You Can Do

<CardGroup>
  <Card title="View Campaign Hierarchy" icon="sitemap">
    Navigate through campaigns → ad sets → ads with intuitive breadcrumb navigation
  </Card>

  <Card title="Unified Metrics" icon="chart-line">
    See Meta ad metrics (spend, clicks, impressions) alongside funnel metrics (revenue, sales, profit) in one view
  </Card>

  <Card title="Control Campaigns" icon="sliders">
    Pause, activate, and update budgets for campaigns, ad sets, and ads directly from the interface
  </Card>

  <Card title="Ad Preview" icon="eye">
    Preview ad creatives including images and videos without leaving the dashboard
  </Card>

  <Card title="Date Range Analysis" icon="calendar">
    Select custom date ranges to analyze performance over any time period
  </Card>

  <Card title="Filter & Search" icon="filter">
    Filter by status and search by campaign name, ID, or objective
  </Card>
</CardGroup>

## Getting Started

### Prerequisites

Before using Campaigns Management, you need:

1. **An advertising integration** - Connect your ad platform first
   * Go to **Settings → Integrations → Advertising**
   * Set up [Meta Ads](/integrations/meta-ads) or [Google Ads](/integrations/google-ads)
   * Ensure you've selected an ad account on the integration

2. **Tracking Links Created with Tracking Link Builder** - **Required** for funnel analytics
   * You **must** use the [Tracking Link Builder](/integrations/affiliate-tracking#tracking-link-builder) to create tracking URLs
   * Select the matching platform in the builder, **Meta Ads** or **Google Ads**, so it writes that platform's parameter format
   * The builder automatically generates the correct UTM parameters:
     * `utm_campaign={{campaign.name}}` (maps to campaign name)
     * `utm_content={{adset.name}}` (maps to ad set name)
     * `utm_term={{ad.name}}` (maps to ad name)
     * `adid=fb_{{ad.id}}` (required for ad spend tracking)

<Warning>
  **Critical:** Without using the Tracking Link Builder to create your URLs with the predefined Meta Ads parameters, you'll only see Meta's ad metrics (spend, clicks, impressions). Funnel metrics (revenue, sales, profit) will not appear because the system requires the specific parameter format generated by the Tracking Link Builder.
</Warning>

<Info>
  The Tracking Link Builder can be accessed from:

  * **Tools → Tracking → Tracking Link Builder**
  * **Pages list** → Dropdown → "Get Tracking Link"
  * **Funnels list** → Dropdown → "Get Tracking Link"

  See the [Setting Up UTM Tracking](#setting-up-utm-tracking) section below for detailed instructions.
</Info>

### Accessing Campaigns Management

1. Go to **Reports → Ad Campaigns** in the sidebar
2. Pick the integration you want to view from the list of connected ad platforms
3. You'll see your campaigns list

If no advertising integration is connected yet, this screen explains what the feature does and links you to the Advertising tab to connect one.

<Info>
  If you have several integrations on the same platform, make sure you pick the one connected to the ad account you want to manage. The integration name is shown next to the platform.
</Info>

## Understanding the Interface

### Campaign Hierarchy

Campaigns Management uses a three-level hierarchy:

```
Campaigns (Top Level)
  └── Ad Sets (Second Level)
      └── Ads (Third Level)
```

**Navigation:**

* Click a **campaign name** to view its ad sets
* Click an **ad set name** to view its ads
* Click an **ad name** to preview the creative
* Use the **breadcrumb navigation** to go back to any level
* Click **"Campaigns"** in the breadcrumb to return to the top level

### View Levels

<AccordionGroup>
  <Accordion title="Campaign Level">
    Shows all campaigns in your selected ad account.

    **Columns:**

    * Campaign Name
    * Status
    * Objective
    * Budget
    * Performance metrics (when date range selected)
    * Funnel analytics (when date range selected)

    **Actions:**

    * Pause/Activate
    * Update Budget
    * View Ad Sets
  </Accordion>

  <Accordion title="Ad Set Level">
    Shows all ad sets within a selected campaign.

    **Columns:**

    * Ad Set Name
    * Status
    * Budget
    * Performance metrics (when date range selected)
    * Funnel analytics (when date range selected)

    **Actions:**

    * Pause/Activate
    * Update Budget
    * View Ads

    <Note>
      Ad set status may show parent campaign status if the campaign is paused or archived.
    </Note>
  </Accordion>

  <Accordion title="Ad Level">
    Shows all ads within a selected ad set.

    **Columns:**

    * Ad Name
    * Status
    * Performance metrics (when date range selected)
    * Funnel analytics (when date range selected)

    **Actions:**

    * Pause/Activate
    * Preview Ad Creative

    <Note>
      Ad status may show parent ad set or campaign status if either parent is paused or archived.
    </Note>
  </Accordion>
</AccordionGroup>

## Metrics Explained

### Meta Ad Metrics

These come directly from Meta's API and show your advertising performance:

<CardGroup>
  <Card title="Spend" icon="dollar-sign">
    Total amount spent on ads in the selected date range
  </Card>

  <Card title="Impressions" icon="eye">
    Number of times your ads were shown
  </Card>

  <Card title="Clicks" icon="cursor-click">
    Number of clicks on your ads
  </Card>

  <Card title="CPM" icon="chart-bar">
    Cost per 1,000 impressions
  </Card>

  <Card title="CPC" icon="cursor-click">
    Cost per click
  </Card>

  <Card title="CTR" icon="percent">
    Click-through rate (clicks ÷ impressions)
  </Card>
</CardGroup>

### Funnel Analytics Metrics

These come from your ElasticFunnels tracking and show conversion performance:

<CardGroup>
  <Card title="Funnel Revenue" icon="dollar-sign">
    Total revenue from conversions attributed to this campaign/ad set/ad
  </Card>

  <Card title="Funnel Sales" icon="shopping-cart">
    Number of sales/conversions
  </Card>

  <Card title="Funnel Profit" icon="trending-up">
    Net revenue minus ad spend and COGS
  </Card>

  <Card title="RPC" icon="calculator">
    Revenue per click (revenue ÷ clicks)
  </Card>

  <Card title="PPC" icon="calculator">
    Profit per click (profit ÷ clicks)
  </Card>

  <Card title="CPA" icon="calculator">
    Cost per acquisition (spend ÷ sales)
  </Card>

  <Card title="CVR" icon="percent">
    Conversion rate (sales ÷ clicks)
  </Card>

  <Card title="AOV" icon="dollar-sign">
    Average order value (revenue ÷ sales)
  </Card>
</CardGroup>

<Info>
  Funnel analytics require proper UTM parameters in your tracking URLs. See the "Setting Up UTM Tracking" section below.
</Info>

## Setting Up UTM Tracking

For funnel analytics to work correctly, your Meta Ads tracking URLs **must** use the specific UTM parameters predefined in the Tracking Link Builder. These parameters are required for proper attribution and to display funnel metrics in Campaigns Management.

<Warning>
  **You must use the Tracking Link Builder** to generate tracking URLs with the correct parameter format. Manually creating URLs may result in missing or incorrect parameters, which will prevent funnel analytics from appearing.
</Warning>

### Required UTM Parameters (Predefined Format)

The Tracking Link Builder automatically generates URLs with these specific parameters for Meta Ads:

```
utm_source={{site_source_name}}
utm_medium={{placement}}
utm_campaign={{campaign.name}}
utm_content={{adset.name}}
utm_term={{ad.name}}
adid=fb_{{ad.id}}
```

<Info>
  The `{{...}}` tokens are dynamic placeholders that Meta Ads automatically replaces with actual values when someone clicks your ad. This ensures accurate tracking even if you rename campaigns later.
</Info>

### Using the Tracking Link Builder

**Recommended Method: Use the Tracking Link Builder**

The Tracking Link Builder is the **only supported way** to create tracking URLs for Campaigns Management. It ensures:

* ✅ Correct UTM parameter format
* ✅ Proper `adid` parameter for ad spend tracking
* ✅ Dynamic tokens that auto-update with campaign names
* ✅ Compatibility with all Meta Ads features

**How to Access:**

<AccordionGroup>
  <Accordion title="From Tools Menu">
    1. Navigate to **Tools** in the main menu
    2. Click on the **Tracking** tab
    3. Select **Tracking Link Builder**
    4. Select **Meta Ads** from the "Auto Cost Update" dropdown
    5. Choose your destination (URL, Page, or Funnel)
    6. Copy the generated link
  </Accordion>

  <Accordion title="From Pages List">
    1. Go to **Pages** in the main menu
    2. Find the page you want to create a tracking link for
    3. Click the dropdown menu (three dots) on the page row
    4. Select **"Get Tracking Link"**
    5. The builder opens with your page pre-selected
    6. Select **Meta Ads** from the "Auto Cost Update" dropdown
    7. Copy the generated link
  </Accordion>

  <Accordion title="From Funnels List">
    1. Go to **Funnels** in the main menu
    2. Find the funnel you want to create a tracking link for
    3. Click the dropdown menu (three dots) on the funnel row
    4. Select **"Get Tracking Link"**
    5. The builder opens with your funnel pre-selected
    6. Select **Meta Ads** from the "Auto Cost Update" dropdown
    7. Copy the generated link
  </Accordion>
</AccordionGroup>

### Generated URL Format

When you use the Tracking Link Builder with Meta Ads selected, it generates a URL like this:

```
https://yourfunnel.com/landing-page?
  utm_source={{site_source_name}}&
  utm_medium={{placement}}&
  utm_campaign={{campaign.name}}&
  utm_content={{adset.name}}&
  utm_term={{ad.name}}&
  adid=fb_{{ad.id}}
```

<Info>
  For detailed instructions on using the Tracking Link Builder, including all available tokens and platform-specific templates, see the [Tracking Link Builder documentation](/integrations/affiliate-tracking#tracking-link-builder).
</Info>

### Critical Requirements

<Warning>
  **Parameter Matching:** The UTM parameter values must **exactly match** your campaign, ad set, and ad names in Meta Ads for proper attribution. The Tracking Link Builder uses dynamic tokens (`{{campaign.name}}`, etc.) that automatically match, but if you manually edit the URL, ensure exact matching.

  **Required Parameters:** All of these parameters must be present:

  * `utm_campaign` (maps to campaign name)
  * `utm_content` (maps to ad set name)
  * `utm_term` (maps to ad name)
  * `adid` (required for ad spend tracking)
</Warning>

### What Happens Without Proper Parameters

If your tracking URLs don't use the predefined format from the Tracking Link Builder:

* ❌ Funnel metrics (revenue, sales, profit) will show as zero
* ❌ Ad spend tracking may not work correctly
* ❌ ROI calculations will be inaccurate
* ❌ Campaign-level attribution will fail

<Info>
  If you're not seeing funnel metrics in Campaigns Management, verify that:

  1. You used the Tracking Link Builder to create your URLs
  2. You selected "Meta Ads" as the platform
  3. The URLs are correctly added to your Meta Ads campaigns
  4. You have conversions in the selected date range
</Info>

## Using Date Ranges

Date ranges control which metrics are displayed:

### Without Date Range

* Shows only basic information (name, status, budget)
* No performance metrics
* No funnel analytics

### With Date Range

* Shows all Meta ad metrics (spend, clicks, impressions, etc.)
* Shows all funnel analytics (revenue, sales, profit, etc.)
* Metrics are calculated for the selected time period

### How to Select a Date Range

1. Use the **date range picker** in the top-right of the campaigns interface
2. Select your start and end dates
3. Metrics will automatically update
4. The date range is saved in the URL, so you can bookmark specific date ranges

<Tip>
  Use date ranges to compare performance across different time periods. Try comparing this month vs. last month to see trends.
</Tip>

## Managing Campaigns

### Pausing and Activating

You can pause or activate campaigns, ad sets, and ads directly from the interface:

1. Find the item you want to pause/activate
2. Click the **"Pause"** or **"Activate"** button in the Actions column
3. Confirm the action in the modal
4. The status will update immediately

<Warning>
  * Pausing a **campaign** pauses all its ad sets and ads
  * Pausing an **ad set** pauses all its ads
  * If a parent is paused, child items will show the parent's status
</Warning>

### Updating Budgets

You can update daily or lifetime budgets for campaigns and ad sets:

1. Click the **"Budget"** button in the Actions column
2. Enter either:
   * **Daily Budget**: Maximum spend per day
   * **Lifetime Budget**: Total spend for the campaign/ad set
3. Click **"Update"**
4. Changes take effect immediately in Meta Ads

<Info>
  Budget amounts are in your ad account's currency. Budgets are stored in cents internally but displayed in dollars.
</Info>

### Previewing Ad Creatives

For ads, you can preview the creative assets:

1. Click an **ad name** or the **eye icon** next to it
2. A modal will open showing:
   * **Image previews** (if available)
   * **Video previews** (if available)
   * **Creative details** (ID, name, landing page URL)
   * **Download links** for video sources (MP4)

<Note>
  Video previews may take a moment to load as we fetch the direct video source from Meta's API.
</Note>

## Filtering and Searching

### Status Filter

Filter campaigns, ad sets, or ads by status:

* **All** - Show all items regardless of status
* **Active** - Only show active items
* **Paused** - Only show paused items
* **Archived** - Only show archived items

### Search

Use the search box to find specific items by:

* Campaign/Ad Set/Ad name
* ID
* Objective (for campaigns)

The search is case-insensitive and searches across multiple fields simultaneously.

## Refreshing Data

### Manual Refresh

Click the **refresh button** (circular arrow icon) to manually sync data from Meta Ads.

<Warning>
  To prevent rate limiting, refreshes are throttled to once every 30 seconds. If you try to refresh too soon, you'll see a warning message.
</Warning>

### Automatic Sync

Campaign data is automatically synced every 2 hours. However, for real-time status changes and budget updates, use the manual refresh button.

## Understanding Status Display

The status column shows the effective status, which may be affected by parent items:

### Campaign Level

* Shows the campaign's actual status

### Ad Set Level

* If campaign is paused: Shows "Campaign paused"
* If ad set is active but campaign is paused: Shows "Active but campaign paused"
* Otherwise: Shows the ad set's status

### Ad Level

* If ad set is paused: Shows "Ad Set paused"
* If campaign is paused: Shows "Campaign paused"
* If ad is active but parent is paused: Shows "Active but \[parent] paused"
* Otherwise: Shows the ad's status

<Info>
  This status display helps you understand why an ad might not be running even if it's set to "Active" in the ad platform.
</Info>

Google Ads behaves the same way, reading ad groups in place of ad sets. An enabled ad group inside a paused campaign shows **Active but campaign paused**, and an enabled ad inside a paused ad group shows the paused parent rather than claiming to be running.

## Best Practices

<Steps>
  <Step title="Set Up UTM Tracking First">
    Before analyzing funnel metrics, ensure your tracking URLs include the correct UTM parameters. Use the Tracking Link Builder for accuracy.
  </Step>

  <Step title="Use Date Ranges for Analysis">
    Always select a date range when analyzing performance. Without a date range, you'll only see basic information without metrics.
  </Step>

  <Step title="Monitor Profit, Not Just Revenue">
    Use the "Funnel Profit" column to see true ROI. A campaign with high revenue but negative profit needs optimization.
  </Step>

  <Step title="Compare RPC vs CPC">
    If RPC (Revenue Per Click) is higher than CPC (Cost Per Click), your campaign is profitable. Use this to identify winning campaigns.
  </Step>

  <Step title="Check Parent Status">
    If an ad set or ad shows unexpected status, check if the parent campaign is paused. The status display will indicate this.
  </Step>

  <Step title="Refresh After Changes">
    After making changes in Meta Ads Manager, use the refresh button to see updates in ElasticFunnels immediately.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No Metrics Showing">
    **Possible Causes:**

    * No date range selected (metrics require a date range)
    * No ad spend in the selected date range
    * Date range is in the future

    **Solution:** Select a date range that includes dates with actual ad activity
  </Accordion>

  <Accordion title="Funnel Metrics Show Zero">
    **Possible Causes:**

    * Not using Tracking Link Builder to create URLs (most common)
    * Missing UTM parameters in tracking URLs
    * UTM parameter values don't match campaign/ad set/ad names exactly
    * No conversions in the selected date range

    **Solution:**

    1. **Use the Tracking Link Builder** - This is required. Go to Tools → Tracking → Tracking Link Builder, select Meta Ads platform, and generate your URLs
    2. Verify the generated URLs include all required parameters: `utm_campaign`, `utm_content`, `utm_term`, and `adid`
    3. Ensure you're using the URLs generated by the builder in your Meta Ads campaigns
    4. Check that you have conversions in the selected date range

    <Info>
      The Tracking Link Builder automatically generates the correct parameter format. If you manually created URLs or edited the builder's output, you may have broken the required format.
    </Info>
  </Accordion>

  <Accordion title="Status Changes Not Reflecting">
    **Cause:** Data syncs every 2 hours automatically

    **Solution:** Click the refresh button to manually sync latest data from Meta Ads
  </Accordion>

  <Accordion title="Can't See My Campaigns">
    **Possible Causes:**

    * Wrong integration selected
    * Integration not connected to the correct ad account
    * No campaigns in the ad account

    **Solution:**

    1. Verify you're viewing the correct Meta Ads integration
    2. Check that the integration is connected to the right ad account
    3. Confirm campaigns exist in Meta Ads Manager
  </Accordion>

  <Accordion title="Budget Update Fails">
    **Possible Causes:**

    * Invalid budget amount
    * Campaign/ad set is archived
    * Insufficient permissions

    **Solution:**

    1. Ensure budget is a positive number
    2. Check that the item is not archived
    3. Verify you have edit permissions in Meta Ads
  </Accordion>

  <Accordion title="Ad Preview Not Loading">
    **Possible Causes:**

    * Ad has no creative attached
    * Video source unavailable
    * Network issues

    **Solution:**

    1. Check if the ad has creative data in Meta Ads Manager
    2. Wait a moment for video sources to load
    3. Try refreshing the page
  </Accordion>
</AccordionGroup>

## Integration with Other Features

### Analytics Dashboard

Campaign data from Campaigns Management feeds into your main Analytics dashboard:

* Ad spend metrics appear in **Analytics → Ad Spend Reports**
* Conversion data is used for ROI calculations
* Profit metrics help identify winning campaigns

### Tracking Link Builder

**Required for Campaigns Management:** The Tracking Link Builder is the only supported way to create tracking URLs that work with Campaigns Management.

**How to Use:**

1. Access the builder:
   * **Tools → Tracking → Tracking Link Builder**, OR
   * **Pages list** → Dropdown → "Get Tracking Link", OR
   * **Funnels list** → Dropdown → "Get Tracking Link"
2. Select your destination (URL, Page, or Funnel)
3. **Select "Meta Ads" from the "Auto Cost Update" dropdown** (critical step)
4. The builder automatically generates URLs with the correct UTM structure:
   * `utm_campaign={{campaign.name}}`
   * `utm_content={{adset.name}}`
   * `utm_term={{ad.name}}`
   * `adid=fb_{{ad.id}}`
5. Copy the generated link and use it in your Meta Ads campaigns

<Info>
  For complete documentation on the Tracking Link Builder, including all available tokens and platform templates, see the [Tracking Link Builder guide](/integrations/affiliate-tracking#tracking-link-builder).
</Info>

### Conversion Tracking

Campaigns Management works alongside your Meta Ads integration's conversion postbacks:

* Postbacks send conversion data to Meta
* Campaigns Management shows that same data in your funnel metrics
* Both use the same UTM parameters for attribution

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="How often is campaign data updated?">
    Campaign data syncs automatically every 2 hours. You can also manually refresh using the refresh button (throttled to once per 30 seconds).
  </Accordion>

  <Accordion title="Why don't I see funnel metrics?">
    Funnel metrics require:

    1. A date range selected
    2. Proper UTM parameters in your tracking URLs
    3. UTM values that exactly match your campaign/ad set/ad names
    4. Actual conversions in the selected date range
  </Accordion>

  <Accordion title="Can I manage campaigns for multiple ad accounts?">
    Yes! Create separate Meta Ads integrations for each ad account. Each integration has its own Campaigns Management view.
  </Accordion>

  <Accordion title="What's the difference between Meta metrics and Funnel metrics?">
    **Meta metrics** come from Meta's API (spend, clicks, impressions) and show advertising performance.

    **Funnel metrics** come from your ElasticFunnels tracking (revenue, sales, profit) and show conversion performance.

    Together, they give you complete ROI visibility.
  </Accordion>

  <Accordion title="Can I export campaign data?">
    Currently, export functionality is not available in Campaigns Management. Use the Analytics dashboard for export capabilities.
  </Accordion>

  <Accordion title="Why does my ad show 'Active but campaign paused'?">
    This means the ad itself is set to "Active" in Meta Ads, but its parent campaign is paused. Meta won't serve the ad because the campaign is paused, even though the ad status is active.
  </Accordion>

  <Accordion title="How do I know if my UTM tracking is working?">
    If you see funnel metrics (revenue, sales, profit) with non-zero values, your UTM tracking is working correctly.

    If all funnel metrics are zero:

    1. Verify you used the Tracking Link Builder to create your URLs
    2. Confirm you selected "Meta Ads" as the platform in the builder
    3. Check that the URLs are correctly added to your Meta Ads campaigns
    4. Ensure you have conversions in the selected date range

    <Warning>
      Manually created URLs or URLs not generated by the Tracking Link Builder will not work with Campaigns Management.
    </Warning>
  </Accordion>

  <Accordion title="Can I create new campaigns from ElasticFunnels?">
    Currently, Campaigns Management is for viewing and managing existing campaigns. Create new campaigns in Meta Ads Manager, then they'll appear in ElasticFunnels after the next sync.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Meta Ads Integration" icon="rectangle-ad" href="/integrations/meta-ads">
    Learn how to set up your Meta Ads integration
  </Card>

  <Card title="Tracking Link Builder" icon="link" href="/integrations/affiliate-tracking#tracking-link-builder">
    Learn how to create tracking URLs with the correct parameters
  </Card>

  <Card title="Analytics Dashboard" icon="chart-mixed" href="/analytics/overview">
    View unified analytics across all your campaigns
  </Card>

  <Card title="Ad Spend Reports" icon="dollar-sign" href="/analytics/ad-spend">
    Deep dive into ad performance metrics
  </Card>
</CardGroup>


# Chargeback Management
Source: https://docs.elasticfunnels.io/integrations/chargeback-management

Prevent and manage chargebacks with automated alert monitoring, auto-refund rules, and dispute representment via Dispute.com.

## Overview

The chargeback management integration connects ElasticFunnels to third-party chargeback prevention services. When a customer initiates a dispute with their bank, these services detect it **before** it becomes a formal chargeback and notify ElasticFunnels in real time. You can then auto-refund the transaction to prevent the chargeback, or fight it with evidence.

<Info>
  This integration only works with **direct payment gateways** where ElasticFunnels can issue refunds (NMI, Stripe, Klarna). Platforms like BuyGoods, ClickBank, and Digistore24 handle chargebacks through their own systems.
</Info>

## Supported Providers

<CardGroup>
  <Card title="Dispute.com" icon="shield-check">
    Alert monitoring (Ethoca & Verifi CDRN), Rapid Dispute Resolution (RDR), and chargeback representment.
  </Card>

  <Card title="Chargebacks911" icon="shield-halved">
    Real-time pre-chargeback alerts and case updates via webhook. Order data is pushed back to Chargebacks911 for better transaction matching and representment.
  </Card>
</CardGroup>

<Info>
  Both providers can run in parallel — for example, Dispute.com for alert auto-refunds and Chargebacks911 for representment on filed chargebacks. Each integration is assigned to merchants independently.
</Info>

## How It Works

### Dispute.com flow

Dispute.com monitors card network activity for your merchant accounts. When a customer begins a dispute process, the flow is:

1. **Alert Received** — Dispute.com detects a pre-chargeback alert from the card network (Ethoca or Verifi CDRN) and sends a notification to ElasticFunnels.
2. **Transaction Matched** — ElasticFunnels matches the alert to the original order using the transaction ID, order ID, or card details.
3. **Auto-Refund Check** — If you've configured auto-refund rules and the transaction meets the criteria (amount threshold, merchant, alert type), ElasticFunnels automatically issues a refund through your payment gateway.
4. **Alert Responded** — ElasticFunnels notifies Dispute.com that the refund was processed, preventing the chargeback from being filed.
5. **Chargeback Prevented** — The dispute is resolved before it becomes a formal chargeback on your merchant account.

If a chargeback is filed despite prevention (or no alert was received), Dispute.com can help fight it through representment — compiling and submitting evidence to the card network.

### Rapid Dispute Resolution (RDR)

For Visa transactions, Dispute.com can automatically resolve disputes through Visa's RDR program before they become chargebacks. These are logged in your dashboard as auto-resolved cases.

### Chargebacks911 flow

Chargebacks911 monitors card-network activity (Visa, Mastercard) on your merchant accounts and sends alerts and case updates over webhook. The flow is:

1. **Order pushed** — When a conversion is created in ElasticFunnels for an eligible merchant, order data (transaction ID, customer, amount, products) is sent to Chargebacks911 to power transaction matching.
2. **Alert received** — Chargebacks911 detects a pre-chargeback alert or case update and posts it to ElasticFunnels.
3. **Auto-refund check** — If you've enabled auto-refund and the alert matches your rules, ElasticFunnels refunds the original transaction through the payment gateway.
4. **Case updates** — Status changes (won, lost, in\_progress) are posted as additional webhook events and surfaced in the Chargebacks page.

## Eligible Gateways

Chargeback management requires a gateway where ElasticFunnels has direct API access to issue refunds:

| Gateway | Supported | Why |
| - | - | - |
| **NMI** | Yes | Direct refund API |
| **Stripe** | Yes | Direct refund API |
| **Klarna** | Yes | Direct refund API |
| BuyGoods | No | Chargebacks handled by BuyGoods |
| ClickBank | No | Chargebacks handled by ClickBank |
| Digistore24 | No | Chargebacks handled by Digistore24 |

When you set up the integration, the merchant selector only shows merchants using eligible gateways. Merchants on unsupported gateways are automatically excluded.

## Setup — Dispute.com

<Steps>
  <Step title="Get your Dispute.com API key">
    Log in to your Dispute.com dashboard and generate an API key. You'll need either an **Account Key** (for a single account) or an **Organization Key** (for multiple accounts).
  </Step>

  <Step title="Create the integration">
    Go to **Settings → Integrations** in ElasticFunnels. Click **Add Integration** and select **Dispute.com** under the Chargeback category. Enter your API key and save.
  </Step>

  <Step title="Test the connection">
    After saving, click **Test Connection** to verify your API key is valid and Dispute.com is reachable.
  </Step>

  <Step title="Configure merchant filtering">
    Choose which merchants this integration applies to. You can select **All eligible merchants** (default) or use a **Whitelist** or **Blacklist** to target specific ones. Only merchants using NMI, Stripe, or Klarna will appear in the list.
  </Step>

  <Step title="Set up auto-refund rules">
    Enable **Auto-Refund** and configure your rules:

    * **Maximum amount** — Only auto-refund alerts below this dollar amount (e.g., \$50)
    * **Alert types** — Choose which alert types trigger auto-refund (Ethoca, Verifi CDRN, or both)
    * **Cancel subscription** — Automatically cancel the customer's subscription when an alert is refunded
    * **Flag customer** — Mark the customer as a chargebacker for future reference

    Alerts that don't match your rules are logged for manual review.
  </Step>
</Steps>

## Setup — Chargebacks911

<Steps>
  <Step title="Get your Chargebacks911 credentials">
    Contact your Chargebacks911 account manager and request API access. You'll receive credentials used for the order-push API and a webhook secret used to verify incoming alerts.
  </Step>

  <Step title="Create the integration">
    In ElasticFunnels, go to **Settings → Integrations**, click **Add Integration**, and select **Chargebacks911** under the Chargeback category. Enter your credentials and save.
  </Step>

  <Step title="Send the webhook URL">
    Copy the **Webhook URL** shown on the integration form and send it to your Chargebacks911 contact so they can configure outbound alerts to ElasticFunnels.
  </Step>

  <Step title="Configure merchant filtering">
    Assign the integration to specific merchants (recommended) or all eligible merchants. Order data is only pushed for merchants in scope.
  </Step>

  <Step title="(Optional) Enable auto-refund">
    The same auto-refund rules described above apply to Chargebacks911 alerts. Configure them on the integration form if you want EF to refund automatically before a chargeback is filed.
  </Step>
</Steps>

<Tip>
  Start with a conservative auto-refund threshold (e.g., $30–$50) and monitor the results before increasing it. You can always manually handle higher-value alerts.
</Tip>

## Auto-Refund Rules

Auto-refund rules are processed entirely by ElasticFunnels when an alert arrives from Dispute.com. The rules are evaluated in order:

1. Is auto-refund **enabled** for this integration?
2. Is the disputed amount **≤** the maximum threshold?
3. Does the alert type match (Ethoca / CDRN)?
4. Does the merchant match the filter (whitelist/blacklist)?
5. Is the merchant's gateway **eligible** for refunds?

If all conditions pass, ElasticFunnels:

* Issues a refund through the payment gateway
* Responds to Dispute.com confirming the refund
* Optionally cancels the subscription and flags the customer

If any condition fails, the alert is logged for manual review in the Chargebacks section of your dashboard.

## Monitoring

### Chargebacks Page

Navigate to **Conversions → Chargebacks** to see all chargeback-related activity:

* **Alerts** — Pre-chargeback alerts received, with status (auto-refunded, manually reviewed, declined)
* **Chargebacks** — Filed chargebacks, with representment status (pending, won, lost)
* **RDR Cases** — Disputes auto-resolved through Visa's RDR program

### Conversion Detail

Each conversion that has chargeback activity shows a **Chargeback Services** card in the conversion drawer. This displays the alert/chargeback history, current status, and any actions taken.

## FAQ

<AccordionGroup>
  <Accordion title="Do I need to set up anything on Dispute.com's side?">
    No. When you save the integration, ElasticFunnels automatically registers the necessary webhooks with Dispute.com. Your Dispute.com account just needs an active API key and the relevant alert monitoring services enabled (Ethoca, Verifi CDRN, or RDR).
  </Accordion>

  <Accordion title="What happens if auto-refund is disabled?">
    Alerts are still received and logged in your dashboard. You can review them and take manual action (refund or decline) from the Chargebacks page.
  </Accordion>

  <Accordion title="Can I use this with BuyGoods or ClickBank merchants?">
    No. These platforms manage chargebacks through their own systems. The Dispute.com integration only applies to merchants using NMI, Stripe, or Klarna where ElasticFunnels has direct refund access.
  </Accordion>

  <Accordion title="How does ElasticFunnels match alerts to orders?">
    When Dispute.com sends an alert, ElasticFunnels matches it using the transaction ID, order ID, ARN (Acquirer Reference Number), and card details (last four digits + amount). If no match is found, the alert is logged as unmatched for manual review.
  </Accordion>

  <Accordion title="What is RDR?">
    Rapid Dispute Resolution is a Visa program that allows disputes to be automatically resolved before they become formal chargebacks. Dispute.com handles this based on rules you configure in their dashboard. ElasticFunnels logs these as prevented chargebacks.
  </Accordion>
</AccordionGroup>


# Clickbank Integration
Source: https://docs.elasticfunnels.io/integrations/clickbank

Connect Clickbank for affiliate tracking, automated conversions, and secure postback validation

## Overview

Clickbank S2S (Server-to-Server) integration handles postbacks from the Clickbank affiliate network. The integration receives webhook postbacks, creates conversion records, and provides automation triggers for Clickbank events. It uses secret key encryption for secure postback validation.

## What This Integration Provides

<CardGroup>
  <Card title="Secure Postbacks" icon="lock">
    Secret key encryption for secure postback validation
  </Card>

  <Card title="Real-time Tracking" icon="bolt">
    Instant notification of sales and commissions
  </Card>

  <Card title="Automation Triggers" icon="workflow">
    Trigger automation workflows on Clickbank postbacks
  </Card>

  <Card title="Transaction Types" icon="list">
    Support for purchases, refunds, chargebacks, and upsells
  </Card>
</CardGroup>

## Setup Guide

### Step 1: Get Your Secret Key

<Warning>
  **Important:** Clickbank uses a **Secret Key** (not an API key) for postback validation. This is different from other integrations.
</Warning>

1. Log into your ClickBank account
2. Go to **Settings → My Account**
3. Navigate to the **Secret Key** section (not API Keys)
4. Generate or copy your Secret Key
5. Keep this key secure - you'll need it for validation

<Info>
  The Secret Key is used to validate that postbacks are actually coming from Clickbank. It's encrypted and stored securely in ElasticFunnels.
</Info>

### Step 2: Configure Integration

1. Go to **Settings → Integrations → Affiliate Networks**
2. Find **Clickbank (S2S)** and click **"Activate"** or **"Manage"**
3. Enter your **Secret Key**
4. Copy the **Postback URL** provided
5. Save the integration

<Note>This integration is used as an affiliate. To set up ClickBank as a merchant, see [ClickBank](/merchants/clickbank).</Note>

### Step 3: Configure in Clickbank

1. Log into your ClickBank account
2. Go to **Settings → My Site → Advanced Tools**
3. Navigate to **Postback URLs** or **S2S Postback**
4. Add the postback URL from ElasticFunnels
5. Save your settings

<Check>
  The postback URL is unique to your ElasticFunnels account. Clickbank will send postbacks to this URL when orders are placed.
</Check>

## Secret Key Encryption

### How It Works

The Secret Key is used to validate postbacks:

1. **Encrypted Storage:** Secret key is encrypted before being stored
2. **Postback Validation:** Each postback is validated using the secret key
3. **Security:** Only postbacks with valid secret keys are processed
4. **Privacy:** Secret key is never exposed in logs or responses

### Security Best Practices

* **Never Share:** Keep your secret key secure and never share it
* **Regular Rotation:** Consider rotating your secret key periodically
* **Monitor Usage:** Watch for any unusual postback activity
* **Encrypted Storage:** Secret key is automatically encrypted in ElasticFunnels

<Warning>
  If you suspect your secret key has been compromised, generate a new one in Clickbank and update it in ElasticFunnels immediately.
</Warning>

## Click ID Tracking

### How Click Tracking Works

Clickbank uses click tracking to identify which affiliate links led to conversions:

* **Automatic Tracking:** Click tracking information is automatically captured from Clickbank postbacks
* **Attribution:** Conversions are automatically attributed to the affiliate link that generated the click
* **Validation:** System validates click tracking data before processing conversions

<Info>
  Click tracking information is automatically handled by the system. You don't need to configure anything manually.
</Info>

## Transaction Types

The integration supports multiple transaction types:

<AccordionGroup>
  <Accordion title="Purchase">
    When a customer completes a purchase, Clickbank automatically sends a postback. This creates a purchase conversion in ElasticFunnels.
  </Accordion>

  <Accordion title="Refund">
    When a refund is processed, Clickbank automatically sends a postback. This creates a refund conversion linked to the original purchase.
  </Accordion>

  <Accordion title="Chargeback">
    When a chargeback occurs, Clickbank automatically sends a postback. This creates a chargeback conversion.
  </Accordion>

  <Accordion title="Upsell">
    When an upsell is purchased, Clickbank automatically sends a postback. Upsells are tracked separately from initial purchases.
  </Accordion>
</AccordionGroup>

## Order Tracking

### How Orders Are Tracked

Clickbank uses receipt tracking to link transactions:

* **Purchase Receipts:** Each purchase gets a unique receipt identifier
* **Refund/Chargeback Linking:** Refunds and chargebacks are automatically linked back to the original purchase

### How It Works

When a refund or chargeback occurs, the system automatically links it to the original purchase using receipt tracking. This ensures accurate commission tracking and order history.

<Info>
  Receipt tracking is handled automatically by the system. Refunds and chargebacks are always linked to their original purchases.
</Info>

## Automation Integration

### Triggering Automations

You can trigger automation workflows when Clickbank postbacks are received:

1. Go to **Automations** in the main menu
2. Create or edit an automation
3. Add a trigger node
4. Select **"On Clickbank Postback"** from the trigger options
5. Configure your automation actions

### Use Cases

* **Welcome Emails:** Send welcome emails when purchases are received
* **Follow-up Sequences:** Start email sequences based on Clickbank events
* **CRM Updates:** Update CRM records when conversions occur
* **Custom Workflows:** Build custom automation workflows for Clickbank events

<Info>
  Automation triggers fire automatically when Clickbank postbacks are received and processed successfully.
</Info>

## Tracking Pixels

When you configure Clickbank as a merchant:

* Tracking pixels are automatically created
* Pixels track page views and conversions
* Enables accurate attribution for Clickbank orders
* Works with the pixel attribution system

<Info>
  Tracking pixels are created automatically when the merchant is configured. You don't need to manually set them up.
</Info>

## What Information is Tracked

The integration automatically receives and processes the following information from Clickbank:

* **Order Information:** Receipt ID, transaction type, and order details
* **Customer Information:** Customer email (when available)
* **Transaction Type:** Purchase, refund, chargeback, or upsell
* **Affiliate Earnings:** Commission amount for the transaction
* **Product Information:** Product name or vendor information
* **Click Tracking:** Information about which affiliate link generated the conversion

## Integration Benefits

* **Real-time Tracking**: Instant notification of sales and commissions
* **Automated Reporting**: Automatic sync of performance data
* **Commission Management**: Track earnings across all your promotions
* **Refund Handling**: Automated processing of refunds and chargebacks
* **Secure Validation**: Secret key encryption ensures postback security
* **Automation Support**: Trigger custom workflows based on Clickbank events

## Troubleshooting

<AccordionGroup>
  <Accordion title="Postbacks Not Being Received">
    **Possible Causes:**

    * Postback URL not configured correctly in Clickbank
    * Secret key mismatch
    * Postback URL format incorrect

    **Solution:**

    1. Verify postback URL is copied correctly (no extra spaces)
    2. Check that secret key matches in both Clickbank and ElasticFunnels
    3. Test with a small purchase to verify tracking works
  </Accordion>

  <Accordion title="Secret Key Validation Failing">
    **Issue:** Postbacks are being rejected due to secret key validation

    **Solution:**

    1. Verify secret key is entered correctly in ElasticFunnels
    2. Ensure secret key matches the one in Clickbank
    3. Check that secret key hasn't been rotated in Clickbank
    4. Regenerate secret key if needed
  </Accordion>

  <Accordion title="Refunds Not Linking to Original Purchase">
    **Issue:** Refunds not showing connection to original purchase

    **Solution:**

    1. Verify that the original purchase was processed successfully
    2. Check that Clickbank is sending complete refund information
    3. Contact support if refunds are not linking correctly
  </Accordion>

  <Accordion title="Automation Triggers Not Firing">
    **Issue:** Automations not triggering on Clickbank postbacks

    **Solution:**

    1. Verify automation has "On Clickbank Postback" trigger node
    2. Check that postbacks are being received successfully
    3. Ensure automation is active and enabled
  </Accordion>
</AccordionGroup>

## Best Practices

<Steps>
  <Step title="Secure Your Secret Key">
    Keep your secret key secure and never share it. It's automatically encrypted in ElasticFunnels, but you should still treat it as sensitive information.
  </Step>

  <Step title="Verify Postback URL">
    Double-check that the postback URL is configured correctly in Clickbank. Any typos will prevent postbacks from working.
  </Step>

  <Step title="Test with Small Purchase">
    Test the integration with a small purchase first to verify tracking works before running large campaigns.
  </Step>

  <Step title="Monitor Receipt IDs">
    Monitor receipt IDs to ensure refunds and chargebacks are properly linked to original purchases.
  </Step>

  <Step title="Set Up Automation Triggers">
    Use automation triggers to build custom workflows based on Clickbank events (welcome emails, CRM updates, etc.).
  </Step>

  <Step title="Handle Upsell Transactions">
    Upsell transactions are automatically tracked separately from initial purchases. Monitor your conversion data to see both initial purchases and upsells.
  </Step>
</Steps>

## Security & Privacy

* **Secret Key Encryption:** Secret keys are encrypted before storage
* **Postback Validation:** All postbacks are validated using secret key
* **Secure Storage:** Customer data is handled securely
* **Audit Logging:** All transactions are logged for audit purposes

<Info>
  Allow up to 15 minutes for data to appear after a purchase. Postbacks are processed in real-time, but there may be a slight delay.
</Info>

## Next Steps

<CardGroup>
  <Card title="Clickbank Merchant Setup" icon="store" href="/merchants/clickbank">
    Learn how to set up Clickbank as a merchant
  </Card>

  <Card title="Automation Builder" icon="workflow" href="/automations">
    Set up automation triggers for Clickbank events
  </Card>

  <Card title="Buygoods Integration" icon="link" href="/integrations/buygoods">
    Set up Buygoods for additional affiliate tracking
  </Card>

  <Card title="Analytics Dashboard" icon="chart-mixed" href="/analytics/overview">
    View your conversion and performance data
  </Card>
</CardGroup>


# External CRM Integrations
Source: https://docs.elasticfunnels.io/integrations/crm

Push contacts, deals, and tags into HubSpot, Keap, Ontraport, Pipedrive, Close, and Agile CRM.

## Overview

ElasticFunnels has its own customer-record store and CRM views. The integrations below let you push EF data into an external CRM as well — useful when sales, success, or marketing teams already work inside their CRM and shouldn't have to learn a new tool.

<Info>
  For information on the **built-in** CRM (segments, customer profile, automations), see [CRM overview](/crm/overview).
</Info>

## Supported providers

| Provider | Auth | What you can do |
| - | - | - |
| **HubSpot** | Private App access token | Create / update contacts, write custom contact properties, push deals |
| **Keap** (Infusionsoft) | OAuth 2.0 | Create / update contacts, retrieve a contact, apply tags |
| **Ontraport** | API key + App ID | Create / update contacts, check existence, manage tags |
| **Pipedrive** | API key | Create / update **persons**, create deals on the right pipeline / stage |
| **Close** (`closeio`) | API key | Create / update leads + contacts, push opportunities |
| **Agile CRM** | API key + domain + admin email | Create / update contacts, manage tags |

All six are exposed as actions inside the **Automation Builder** so you can wire them into any flow (form-submit, sale, refund, abandoned cart, dunning failure, etc.).

## Setup pattern

<Steps>
  <Step title="Open the provider in EF">
    Go to **Integrations** → **CRM** and click the provider. The form is provider-specific.
  </Step>

  <Step title="Authenticate">
    Paste an API key (HubSpot Private App token, Pipedrive API key, etc.) or OAuth into the provider (Keap).
  </Step>

  <Step title="Map the right account / pipeline">
    For Pipedrive and Keap, the form loads your pipelines / lists from the provider so you can pick them by name. For HubSpot, the integration writes to your default contact pipeline unless you configure a specific one in your automation.
  </Step>

  <Step title="Add the actions to an automation">
    Open **Automations**, edit a flow, and add an action like `HubSpot: Create or Update Contact`. Map EF variables (`customer.email`, `customer.first_name`, custom fields) to the provider's fields.
  </Step>

  <Step title="Test with a dummy record">
    Trigger the automation manually (Insert Test Run) and verify the record appears in the external CRM.
  </Step>
</Steps>

## Field mapping notes

* **Custom properties / custom fields** — All six providers support custom fields. Add them in the provider first, then they show up in the action's mapping dropdown the next time you open the form.
* **Tag management** — Each provider exposes its own list of tags / labels. EF lists them dynamically; you can also pass a tag name as a string to create it on the fly.
* **Re-keying contacts** — All actions are upsert-style: EF tries to match by email first (or the provider's primary identifier) and updates if a match exists; otherwise it creates a new record.

## When to push, when not to

Don't pipe **every** EF event into your CRM — most CRMs charge per contact and slow down with low-quality records. A common pattern:

* **Push qualified leads** (form-submit, demo-booked) into the CRM immediately.
* **Push customers** (first sale) into the CRM when they hit a paid plan or subscription.
* **Skip abandons** unless your sales team works abandons by hand — keep them inside the EF callcenter or email engine.

You can encode that gating with the EF automation's condition step (e.g. only run the HubSpot action when `total > 0`).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Action fails with 401 / token expired">
    Re-authenticate the integration. HubSpot Private App tokens, Pipedrive API keys, and Ontraport API keys can be regenerated from the provider's dashboard; OAuth-based providers (Keap, AWeber) need to be re-authorized through EF's connect flow.
  </Accordion>

  <Accordion title="Custom field not showing up">
    Create the custom field in the external CRM first, then re-open the EF action — the dropdown is fetched live and will include the new field.
  </Accordion>

  <Accordion title="Duplicate contacts in the CRM">
    Most CRMs match on email. If you have multiple contacts with the same email but different IDs, the EF action picks the first match. Clean up duplicates in the CRM and re-run.
  </Accordion>
</AccordionGroup>


# Email Marketing & Validation Integrations
Source: https://docs.elasticfunnels.io/integrations/email-marketing

Sync contacts, send transactional email, and validate addresses through external email platforms.

## Overview

ElasticFunnels ships its own email engine for broadcasts and automations, but you can also push contacts and send through external platforms when your team already lives there. Every email integration is wired into the **automation builder** as actions you can drop into any workflow (for example, after a form submission or a purchase).

## Categories

<CardGroup>
  <Card title="ESP / contact-sync" icon="envelope">
    Push subscribers, manage tags, and trigger sequences in your existing email service provider.
  </Card>

  <Card title="Transactional email" icon="paper-plane">
    Send one-off API-driven emails through high-deliverability providers (or any SMTP relay).
  </Card>

  <Card title="Email validation" icon="shield-check">
    Verify addresses at form-submit time to keep junk and spam-traps out of your list.
  </Card>
</CardGroup>

## ESP / contact sync

| Provider | Auth | Available actions |
| - | - | - |
| **Klaviyo** | Private API key | Subscribe / update profile, retrieve profile, subscribe to a list (segmentation, predictive analytics) |
| **ActiveCampaign** | API URL + token | Create / update contact, manage tags, add to automation |
| **Mailchimp** | API key | Add / update contact, delete contact, manage tags, check subscription status |
| **GetResponse** | API key | Create / update contact, add to campaign (list), manage tags |
| **Kit (ConvertKit)** | API key (v4) | Create / update subscriber, manage tags, enroll in form / sequence |
| **AWeber** | OAuth 2.0 | Create / update contact (dynamic list selection), manage tags |
| **Brevo** (Sendinblue) | API key | Create / update contact, check existence, manage tags, SMS |
| **Maropost** | API key + account | Send transactional via `emails/deliver.json`, sync contacts |

<Tip>
  **Pick where the source of truth lives.** If Klaviyo or ActiveCampaign already runs your email program, sync EF data into them. If you want to retire your ESP and run broadcasts from EF, use the built-in **Emails** module instead.
</Tip>

## Transactional email

These providers send one-off emails — order receipts, dunning notices, password resets, etc. — through their API or SMTP server.

| Provider | Method | What you control |
| - | - | - |
| **SendGrid** | REST API v3 | Sender identity, stats, bounces, suppression management |
| **Mailgun** | REST API v3 | Sender, mailing lists, bounce / complaint tracking, opens & clicks |
| **Generic SMTP** (labelled "Mailrelay") | Any SMTP relay | Host, port, username, password — works with Gmail, Outlook, Postmark, Amazon SES, etc. |
| **Maropost** | Marketing Cloud REST API | Transactional sends via campaign ID |

<Info>
  The integration shown as **Mailrelay** in the UI is a general-purpose SMTP integration despite the name — point it at any SMTP server you already operate.
</Info>

## Email validation

| Provider | Auth | What it returns |
| - | - | - |
| **ZeroBounce** | API key | Status (`valid`, `invalid`, `catch-all`, `spamtrap`, `unknown`), sub-status, IP / geo enrichment, credit balance |
| **Debounce** | API key | Deliverability + risk classification (`safe_to_send`, `risky`, etc.) |

Both validators plug into:

* **Forms** — call the validator inside the automation that runs after the form is submitted, and reject the row if the address is invalid.
* **Automations** — gate any subsequent step (`add_to_list`, `tag`, `send_email`) on the validation result.

## Setup pattern

The setup is the same for every provider:

<Steps>
  <Step title="Find the provider">
    Go to **Integrations** → **Email Marketing** (or **Validation**), find the provider, click **Activate**.
  </Step>

  <Step title="Authenticate">
    Paste an API key, OAuth your account, or fill in SMTP credentials depending on the provider.
  </Step>

  <Step title="Pick lists / forms (where applicable)">
    For ESP integrations, the form will load your lists, tags, forms, sequences, etc. directly from the provider so you can choose them by name instead of ID.
  </Step>

  <Step title="Use it in automations">
    Open any **Automation** and drop the new actions (e.g. `Klaviyo: Subscribe Profile`) into the workflow. Map ElasticFunnels variables (email, first name, custom fields) to the provider's fields.
  </Step>
</Steps>

## Built-in vs external

ElasticFunnels can replace these tools for many teams. Use the table below to decide:

| Need | Use built-in EF | Use external integration |
| - | - | - |
| Order, dunning, course, login emails | EF Emails (recommended) | SendGrid / Mailgun if you already pay for deliverability |
| Marketing broadcasts to your list | EF Emails (campaigns + segments) | Klaviyo / ActiveCampaign / Mailchimp if your team lives there |
| Behavior-based sequences | EF Automations | ActiveCampaign / Klaviyo automations |
| Validation at form-capture | — | Debounce or ZeroBounce |

You can also mix-and-match — for example, send transactional through SendGrid and broadcasts through Klaviyo, while EF still owns the funnel data, automations, and reporting.


# Everflow Integration
Source: https://docs.elasticfunnels.io/integrations/everflow

Send conversion postbacks to Everflow for attribution tracking and split test optimization

## Overview

The Everflow integration enables outbound conversion tracking to the Everflow affiliate platform. When users click Everflow tracking links and land on your pages, the transaction\_id is captured. When conversions occur (from any payment gateway or affiliate network), postbacks are automatically sent to Everflow with conversion data, enabling accurate attribution and split test tracking.

## What This Integration Provides

<CardGroup>
  <Card title="Conversion Postbacks" icon="arrow-trend-up">
    Automatically send conversion data to Everflow when purchases occur
  </Card>

  <Card title="Split Test Attribution" icon="chart-line">
    Track which landers and pre-landers generate conversions in Everflow
  </Card>

  <Card title="Flexible Parameters" icon="sliders">
    Configurable parameter builder with all Everflow-supported variables
  </Card>

  <Card title="Smart Detection" icon="sparkles">
    Intelligent click ID detection with fallback support for multiple parameter names
  </Card>
</CardGroup>

## How It Works

### The Flow

1. **User clicks Everflow tracking link** → Everflow generates transaction\_id
2. **Everflow redirects to your page** → Appends transaction\_id to URL (e.g., `?transaction_id=ABC123` or `?sub1=ABC123`)
3. **ElasticFunnels captures parameters** → Stored in click tracking data
4. **Customer makes purchase** → Via any payment gateway or affiliate network
5. **Postback automatically sent** → Conversion data sent to Everflow with transaction\_id for attribution

```mermaid theme={null}
graph LR
    A[Everflow Link] --> B[Your Landing Page]
    B --> C[Customer Converts]
    C --> D[ElasticFunnels Captures]
    D --> E[Postback to Everflow]
    E --> F[Attribution in Everflow]
```

### What Makes This Unique

Unlike affiliate network integrations that **receive** conversions, Everflow is **outbound only** - we send conversion data to Everflow for attribution, similar to how Google Ads and Meta Ads integrations work.

<Info>
  This integration is perfect for affiliates and media buyers who want to track which landers and pre-landers generate the best conversions in Everflow.
</Info>

## Setup Guide

### Step 1: Create Everflow Integration

1. Navigate to **Settings → Integrations → Affiliate Networks**
2. Find **Everflow** and click **"Activate"**
3. You'll see the integration configuration form

### Step 2: Get Your Network ID (nid)

<Warning>
  **Required:** You need your Everflow Network ID to send postbacks.
</Warning>

1. Log into your Everflow account
2. Navigate to **Control Center → Configuration**
3. Find your **Network ID (nid)** - it's a number like `1234` or `5678`
4. Copy this ID - you'll need it in the next step

<Info>
  The Network ID identifies your Everflow account. Without it, Everflow won't know where to attribute conversions.
</Info>

### Step 3: Configure Postback Settings

1. Enter your **Network ID (nid)** from Step 2
2. Enter your **Postback Domain** (e.g., `tracking.yournetwork.com` or `www.everflow.io`)
3. The postback URL will be automatically generated

**Option A: Use the sample URL (Quick Start)**

* Click **"Insert sample URL"** to populate with default parameters
* The sample includes: nid, transaction\_id, order\_id, amount, email, currency
* Modify using the parameter builder if needed

**Option B: Edit URL directly**

* The URL field updates automatically as you change Network ID and Domain
* You can also edit it directly and parameters will parse automatically

<Tip>
  Most users can start with the sample URL. It includes all the common parameters Everflow needs.
</Tip>

### Step 4: Configure Click ID Parameter

Select which parameter Everflow uses to pass the transaction ID to your pages:

<AccordionGroup>
  <Accordion title="transaction_id (Default - Most Common)">
    Everflow passes the transaction ID directly as `transaction_id` in the URL.

    **Example:** `yoursite.com/page?transaction_id=ABC123`

    **Use when:** Your Everflow offer is configured with default settings.
  </Accordion>

  <Accordion title="sub1, sub2, sub3, sub4, or sub5">
    Everflow passes the transaction ID via a sub-parameter.

    **Example:** `yoursite.com/page?sub1=ABC123` (transaction\_id passed in sub1)

    **Use when:** Your Everflow offer is configured to pass transaction\_id via a specific sub-parameter.
  </Accordion>
</AccordionGroup>

<Info>
  **How to check:** Look at a sample tracking link from Everflow. The parameter that contains the long unique ID (like "ABC123") is your transaction\_id parameter.
</Info>

### Step 5: Customize Parameters (Optional)

Use the parameter builder to customize what data is sent to Everflow:

1. **Default parameters** are pre-configured (transaction\_id, order\_id, amount, email, currency, timestamp)
2. **Add custom parameters** by clicking "+ Add Parameter"
3. **Select variables** from the dropdown for each parameter
4. **Remove optional parameters** by clicking the X button

**Available Variables:**

* **Required:** transaction\_id, order\_id, amount, currency
* **Customer:** email, firstname, lastname, phone, user\_ip
* **Location:** geo\_country\_code, geo\_country\_name, geo\_region\_name, geo\_city
* **Other:** timestamp, sub1-sub5

<Warning>
  **transaction\_id is required** and cannot be removed. Everflow needs this to attribute conversions correctly.
</Warning>

### Step 6: Configure Merchant Filtering (Optional)

Choose which merchants should send postbacks to Everflow:

**All Merchants (Default):**

* Postbacks sent for conversions from any payment gateway
* Works with any payment gateway or affiliate network

**Specific Merchants:**

* Click "Specific merchants" radio button
* Click "+ Add Merchant" to select merchants
* Only selected merchants will send postbacks to Everflow

<Info>
  Most users leave this set to "All merchants" to track all conversions regardless of payment method.
</Info>

### Step 7: Save and Test

1. Click **"Save Integration"** or **"Update Integration"**
2. Your integration is now active
3. Test by clicking an Everflow tracking link and making a test purchase

## Configuration Options

### Postback URL

The postback URL is a template with macros (like `{transaction_id}`) that get replaced with actual values when sending postbacks.

**Example:**

```
https://tracking.yournetwork.com/?nid=1234&transaction_id={transaction_id}&order_id={order_id}&amount={amount}&email={email}&currency={currency}
```

**When a conversion happens, macros are replaced:**

```
https://tracking.yournetwork.com/?nid=1234&transaction_id=ABC123&order_id=ORD456&amount=99.99&email=customer@example.com&currency=USD
```

<Warning>
  The `nid` parameter is **required** - it identifies your Everflow network account. Get this from Control Center → Configuration in Everflow.
</Warning>

### Click ID Parameter

This tells ElasticFunnels which URL parameter contains Everflow's transaction\_id:

* Most Everflow offers use `transaction_id` directly
* Some offers pass it via `sub1`, `sub2`, etc.
* ElasticFunnels automatically detects it with intelligent fallback

### Smart Fallback Detection

If the configured parameter isn't found, the system automatically checks:

1. `transaction_id`
2. `sub1` through `sub5`

This ensures conversions are tracked even if configuration doesn't exactly match.

## Parameter Builder

### How to Use

The parameter builder gives you full control over what data is sent:

<Steps>
  <Step title="Add Parameter">
    Click "+ Add Parameter" to add a new field to your postback URL
  </Step>

  <Step title="Enter Parameter Name">
    Type the parameter name (e.g., "order\_id", "email", "custom\_field")
  </Step>

  <Step title="Select Variable">
    Choose from the dropdown which data to send (e.g., , , )
  </Step>

  <Step title="View Generated URL">
    The URL field updates automatically as you add/remove parameters
  </Step>
</Steps>

### Two-Way Sync

The URL and parameter builder stay in sync:

* **Edit URL directly** → Parameters automatically parse and display in builder
* **Change parameters** → URL automatically updates
* **Best of both worlds** → Use whichever method is easier for you

## Available Variables

### Required Variables

<ParamField type="string">
  Network ID - Your Everflow account identifier. Find in Control Center → Configuration. **Required to identify your account.**
</ParamField>

<ParamField type="string">
  Everflow click ID captured from the tracking URL. **Required for attribution.**
</ParamField>

<ParamField type="string">
  Your order/conversion ID from ElasticFunnels
</ParamField>

<ParamField type="number">
  Conversion amount (formatted as decimal, e.g., 99.99)
</ParamField>

<ParamField type="string">
  Currency code (e.g., USD, GBP, EUR)
</ParamField>

### Customer Information

<ParamField type="string">
  Customer email address (used for Everflow Email Address Attribution)
</ParamField>

<ParamField type="string">
  Customer first name
</ParamField>

<ParamField type="string">
  Customer last name
</ParamField>

<ParamField type="string">
  Customer phone number
</ParamField>

<ParamField type="string">
  Customer IP address
</ParamField>

### Location Data

<ParamField type="string">
  Two-letter country code (ISO 3166-1 alpha-2)
</ParamField>

<ParamField type="string">
  Full country name
</ParamField>

<ParamField type="string">
  State/region name
</ParamField>

<ParamField type="string">
  City name
</ParamField>

### Other Parameters

<ParamField type="number">
  UNIX timestamp of the conversion (overrides Everflow's timestamp)
</ParamField>

<ParamField type="string">
  Sub-parameter 1 from the original click (if available)
</ParamField>

<ParamField type="string">
  Sub-parameter 2 from the original click (if available)
</ParamField>

<ParamField type="string">
  Sub-parameter 3 from the original click (if available)
</ParamField>

<ParamField type="string">
  Sub-parameter 4 from the original click (if available)
</ParamField>

<ParamField type="string">
  Sub-parameter 5 from the original click (if available)
</ParamField>

## Split Test Tracking

### Why This Matters

If you're running split tests of different landers or pre-landers, Everflow needs to know which variation generated each conversion.

### How It Works

1. **Create split test** in ElasticFunnels (different landing pages)
2. **Use Everflow tracking links** for each variation
3. **Everflow tracks** which link was clicked
4. **Conversions attributed** automatically when postbacks are sent
5. **View results** in Everflow dashboard showing which lander performed best

<Check>
  ElasticFunnels automatically sends the transaction\_id back to Everflow, so attribution happens automatically - no manual tracking needed!
</Check>

## Use Cases

### For Affiliates

Track your promotional performance:

* Which landers convert best
* Split test different pre-landers
* Accurate commission tracking
* Multi-offer campaigns

### For Direct Response Supplement Brands

Track your affiliate network performance:

* Monitor affiliate-driven conversions
* Attribution for different traffic sources
* Split test offer pages
* Campaign optimization data

### For Media Buyers

Optimize your paid traffic:

* Test different landing pages
* Track conversion rates by lander
* Optimize based on actual conversions
* Scale winning variations

## Troubleshooting

<AccordionGroup>
  <Accordion title="No Postbacks Being Sent">
    **Possible Causes:**

    * No transaction\_id in the click data (not from Everflow link)
    * Integration not enabled
    * Postback URL configuration issue

    **Solution:**

    1. Verify customer clicked an Everflow tracking link before purchasing
    2. Check integration is enabled in settings
    3. Verify postback URL format is correct
    4. Check logs for error messages
  </Accordion>

  <Accordion title="Transaction ID Not Found">
    **Issue:** Postbacks not sending because transaction\_id isn't detected

    **Solution:**

    1. Check which parameter Everflow uses to pass transaction\_id (look at a sample tracking link)
    2. Update "Click ID Parameter" dropdown to match
    3. Common options: transaction\_id, sub1, sub2
    4. System automatically checks fallbacks if not found
  </Accordion>

  <Accordion title="Conversions Not Showing in Everflow">
    **Possible Causes:**

    * Postback URL incorrect
    * Transaction\_id not being passed correctly
    * Network timeout or connectivity issue

    **Solution:**

    1. Verify postback URL matches your Everflow configuration
    2. Check Everflow dashboard for incoming postback logs
    3. Test with a small purchase to verify tracking
    4. Review ElasticFunnels logs for postback attempts
  </Accordion>

  <Accordion title="Some Parameters Not Appearing">
    **Issue:** Some variables showing as empty in Everflow

    **Explanation:** This is normal - not all fields are always available:

    * Email, phone, and other customer data depends on what was collected
    * Location data depends on what was tracked during the click
    * Sub-parameters only included if they were in the original tracking URL

    **Solution:** Optional parameters are sent only when available. Everflow handles missing parameters gracefully.
  </Accordion>
</AccordionGroup>

## Best Practices

<Steps>
  <Step title="Start with Sample URL">
    Use the "Insert sample URL" button to get started quickly with recommended parameters.
  </Step>

  <Step title="Verify Click ID Parameter">
    Check a sample Everflow tracking link to confirm which parameter contains the transaction\_id (usually "transaction\_id" or "sub1").
  </Step>

  <Step title="Test with Small Purchase">
    Test the integration with a small purchase first to verify postbacks are being received by Everflow.
  </Step>

  <Step title="Monitor Everflow Dashboard">
    Check your Everflow dashboard to confirm conversions are being attributed correctly to your tracking links.
  </Step>

  <Step title="Use Email Parameter">
    Include the email parameter if your Everflow account supports Email Address Attribution for better tracking.
  </Step>
</Steps>

## Advanced Configuration

### Custom Parameters

You can add any custom parameters Everflow supports:

1. Click **"+ Add Parameter"** in the parameter builder
2. Enter the parameter name
3. Select a variable from the dropdown or enter a custom value
4. The URL updates automatically

### Sub-Parameters

If your original Everflow tracking link included sub-parameters (sub1, sub2, etc.), they're automatically passed through in the postback if you include them in your parameter configuration.

<Tip>
  Sub-parameters are useful for tracking traffic source, campaign, creative, or other custom identifiers through the entire conversion flow.
</Tip>

## Security & Privacy

### Data Handling

* **Transaction ID:** Unique identifier from Everflow (not sensitive)
* **Customer Data:** Only sent if configured (email, name, phone are optional)
* **Hashed Data:** All data is URL-encoded before transmission
* **HTTPS Only:** All postbacks use secure HTTPS connections

### Privacy Considerations

Some Everflow accounts disable PII (Personally Identifiable Information). You can:

* Disable email parameter if needed
* Disable name and phone parameters
* Still track conversions with just order ID and amount

<Info>
  The integration respects your privacy settings. Optional parameters are only sent if configured.
</Info>

## Integration Type

<Note>
  **Important:** Everflow is an **outbound integration** - we send data TO Everflow, we don't receive data FROM Everflow. This is the same pattern as Google Ads and Meta Ads conversion tracking.
</Note>

### What This Means

* **No incoming postbacks** - Everflow doesn't send data to us
* **Triggered by conversions** - Postbacks fire when purchases occur in ElasticFunnels
* **Attribution only** - Used to tell Everflow which tracking links generated conversions
* **Works with any merchant** - Compatible with any payment gateway or affiliate network

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Which parameter should I choose for Click ID Parameter?">
    **Answer:** Look at a sample Everflow tracking link. The parameter containing the long unique ID is your transaction\_id parameter.

    * Most offers use `transaction_id` directly
    * Some offers pass it via `sub1` (check your Everflow offer settings)
    * The system automatically checks fallbacks if the configured parameter isn't found
  </Accordion>

  <Accordion title="Can I use Everflow with my payment processor?">
    **Answer:** Yes! Everflow tracks attribution (which lander generated the conversion), while your payment gateway handles the actual payment processing. They work together perfectly:

    1. Customer clicks Everflow link (transaction\_id captured)
    2. Customer lands on your page
    3. Customer purchases via your payment gateway
    4. ElasticFunnels sends postback to Everflow with transaction\_id
    5. Everflow attributes the conversion to the original tracking link
  </Accordion>

  <Accordion title="How do I track split tests with Everflow?">
    **Answer:**

    1. Create different landing pages in ElasticFunnels
    2. Use Everflow tracking links for each variation
    3. Everflow automatically tracks which link was clicked
    4. When conversions happen, postbacks are sent with the transaction\_id
    5. View results in Everflow showing which lander performed best
  </Accordion>

  <Accordion title="What's the difference between Whitelist and Blacklist?">
    **Answer:**

    * **Whitelist** - Only send postbacks for specific affiliate IDs (e.g., only your top 5 affiliates)
    * **Blacklist** - Block specific affiliate IDs from sending postbacks (e.g., exclude fraudulent affiliates)
    * **All affiliates** - Send postbacks for everyone (default)

    Affiliate IDs come from your payment gateway and identify which affiliate generated the sale.
  </Accordion>

  <Accordion title="Can I filter by both Merchants and Affiliates?">
    **Answer:** Yes! You can combine filters:

    * Merchant filter: Only specific payment gateways
    * Affiliate whitelist: Only specific affiliate IDs
    * Result: Very targeted tracking (e.g., only BuyGoods conversions from affiliate 12345)
  </Accordion>

  <Accordion title="What if I don't see transaction_id in my URL?">
    **Answer:** Everflow might be passing the transaction\_id via a sub-parameter (like sub1). Check your Everflow offer configuration or contact your affiliate manager to find out which parameter is used.
  </Accordion>

  <Accordion title="How long until conversions appear in Everflow?">
    **Answer:** Postbacks are sent immediately when conversions are created (within seconds). Everflow should show the conversion in real-time or within a few minutes.
  </Accordion>

  <Accordion title="Can I test the integration before going live?">
    **Answer:** Yes!

    1. Click an Everflow test tracking link
    2. Make a small test purchase
    3. Check Everflow dashboard to verify the conversion was received
    4. Review ElasticFunnels logs to confirm postback was sent
  </Accordion>

  <Accordion title="What if postbacks fail?">
    **Answer:** The system handles failures gracefully:

    * Failed postbacks are logged for debugging
    * Conversion is still created in ElasticFunnels
    * You can retry by checking the logs and contacting support if needed
    * Postbacks are sent via queue, so temporary network issues are handled automatically
  </Accordion>
</AccordionGroup>

## URL Editing

### Direct URL Editing

You can edit the postback URL directly in the text field:

```
https://api.everflow.io/v1/postback?transaction_id={transaction_id}&order_id={order_id}&amount={amount}
```

The parameter builder will automatically update to show the parsed parameters.

### Parameter Builder

Or use the visual parameter builder:

* Add/remove parameters visually
* Select variables from organized dropdown
* See immediate URL preview
* Required parameters protected from removal

<Tip>
  Both methods work equally well. Use whichever is more comfortable for you - they stay perfectly in sync!
</Tip>

## Technical Details

### Postback Method

Postbacks are sent via **HTTP GET requests** (not POST), which is the standard for Everflow and most affiliate networks.

### Error Handling

The integration reports common errors clearly:

* Failed postbacks are logged but don't break conversion creation
* Network timeouts are handled gracefully
* Invalid URLs are caught and logged
* System continues to work even if Everflow is temporarily unavailable

### Queue Processing

Postbacks are processed asynchronously via Laravel's queue system:

* Doesn't slow down conversion creation
* Automatic retry on temporary failures
* Can be monitored via queue logs

<Info>
  Async processing ensures that even if Everflow is temporarily slow or unavailable, your conversions are still created normally in ElasticFunnels.
</Info>

## Compatibility

### Works With Any Payment Gateway

The Everflow integration works regardless of which payment gateway you use. Everflow tracks attribution (which link/lander generated the conversion), independent of how payment is processed - whether you're using an affiliate network, credit card processor, or any other payment method.

### Works With Split Tests

Compatible with ElasticFunnels' built-in split testing:

* Split test landing pages
* Split test pre-landers
* A/B test offers
* Everflow receives attribution for all variations

## Next Steps

<CardGroup>
  <Card title="Affiliate Tracking" icon="chart-line" href="/integrations/affiliate-tracking">
    Learn about affiliate tracking and attribution
  </Card>

  <Card title="Analytics Dashboard" icon="chart-mixed" href="/analytics/overview">
    View your conversion and performance data
  </Card>

  <Card title="Split Test Analytics" icon="chart-bar" href="/analytics/split-test">
    Analyze your split test performance
  </Card>

  <Card title="Conversion Tracking" icon="bullseye-arrow" href="/analytics/conversions">
    Deep dive into your conversion data
  </Card>
</CardGroup>


# Fulfillment Integration
Source: https://docs.elasticfunnels.io/integrations/fulfillment

Send orders to a 3PL provider (ShipOffers or Jetpack) and reconcile cost of goods automatically.

## Overview

The fulfillment integrations push completed orders to a 3PL (Third-Party Logistics) provider and pull cost-of-goods (COGS) data back so your conversions show real profit, not just revenue.

## Supported providers

<CardGroup>
  <Card title="ShipOffers Fulfillment" icon="ship">
    Pick, pack, and ship through ShipOffers. Multi-hub network in Colorado, Tennessee, and the Netherlands; same-day shipping; real-time tracking.
  </Card>

  <Card title="Jetpack Fulfillment" icon="rocket">
    Multi-hub fulfillment across 65+ warehouses with intelligent inventory distribution (Multi-Hub IQ) and carrier selection (Carrier IQ).
  </Card>

  <Card title="ShipOffers COGS Reconciliation" icon="receipt">
    Automatic email-based ingestion of weekly ShipOffers cost CSVs. Updates each conversion with line-item costs so profit is correct.
  </Card>
</CardGroup>

## How fulfillment dispatch works

1. **Order received** — A customer completes a purchase on your funnel.
2. **Merchant resolution** — The merchant on the conversion is looked up.
3. **Fulfillment provider lookup** — The product's `fulfillment_provider_id` (or merchant default) decides where the order goes. Each product can route to a different provider.
4. **Job queued** — A fulfillment job is queued \~10 seconds after the conversion is finalized so refunds in the first window can short-circuit it.
5. **Order pushed** — Customer info, shipping address, line items (with mapped SKUs), shipping method, and order total are sent to the provider.
6. **Tracking sync** — When the provider returns shipment status and tracking, EF stores it on the conversion and surfaces it in the dashboard. If the order was paid through a [PayPal](/merchants/paypal#tracking-numbers-are-sent-to-paypal) merchant, the tracking number is also sent to PayPal.

<Note>
  Shipping from Shopify instead? With [Shopify Order Sync](/integrations/shopify-order-sync#tracking-back-from-shopify), the tracking your store or its 3PL app adds in Shopify comes back to ElasticFunnels too, and is sent to PayPal for PayPal-paid orders.
</Note>

## Setup — ShipOffers

<Steps>
  <Step title="Get credentials">
    Contact your ShipOffers account manager and request your **Store ID**, **Username**, and **Password**.
  </Step>

  <Step title="Create the integration">
    Go to **Integrations** → **Operations** → **ShipOffers Fulfillment**. Enter the credentials and pick a default shipping service (Standard, Express, etc.).
  </Step>

  <Step title="Map SKUs">
    In ShipOffers, set up your products and copy the SKU codes. In ElasticFunnels, edit each product and ensure its SKU matches the ShipOffers SKU exactly. SKU is what the picker uses to fulfill — mismatched SKUs cause picking errors.
  </Step>

  <Step title="Assign to merchants or products">
    Either set ShipOffers as the **Fulfillment Provider** on a merchant (default for all products under that merchant) or override per product.
  </Step>

  <Step title="(Optional) Enable COGS reconciliation">
    Activate **ShipOffers COGS Reconciliation** as a separate integration, copy the dedicated reconciliation email address, and ask ShipOffers to email weekly cost CSVs to that address. EF parses each CSV and updates the matched conversions with line-item costs.
  </Step>
</Steps>

## Setup — Jetpack

<Steps>
  <Step title="Get credentials">
    Contact Jetpack at jetpackshipping.com or 1-844-4-JETPACK. You'll receive an **API Key ID** and **Secret Key**.
  </Step>

  <Step title="Create the integration">
    Go to **Integrations** → **Operations** → **Jetpack Fulfillment**. Enter your credentials and configure the primary warehouse and shipping preferences.
  </Step>

  <Step title="Map products and SKUs">
    Set up your product catalog inside Jetpack with the same SKU codes you use on each `BrandProduct` in EF.
  </Step>

  <Step title="Assign to merchants or products">
    Set Jetpack as the **Fulfillment Provider** at the merchant level, or override per product when only some products ship from Jetpack.
  </Step>
</Steps>

## SKU mapping

The SKU on every `BrandProduct` in EF must match the SKU your 3PL uses to identify the physical item. Without a match, the order will be rejected by the provider or filled with the wrong product. To set or update the SKU:

1. Go to **Products**.
2. Edit the product.
3. Set its **SKU** to the value from your 3PL catalog.
4. Save.

Re-saving a product does **not** retroactively re-fulfill old orders; only new orders use the updated SKU.

## Monitoring

Go to **Conversions → Fulfillment** to see every fulfillment attempt with its status:

* **Pending** — Queued, waiting for the dispatch window to elapse.
* **Sent** — Provider accepted the order.
* **Failed** — Provider rejected the payload (most often: missing SKU or invalid address). Use the failure detail to fix the data and retry.
* **Tracking** — Provider has shipped the order; the tracking number and carrier are surfaced inline.

<Info>
  If a fulfillment attempt fails because of a bad address, you can manually edit the conversion's shipping address and re-send. SKU mismatches require fixing the product first; orders already in flight are not re-keyed automatically.
</Info>


# Google Ads Integration
Source: https://docs.elasticfunnels.io/integrations/google-ads

Connect Google Ads to track clicks, conversions, and sync ad spend data with automatic postbacks

## Overview

The Google Ads integration syncs ad spend into ElasticFunnels and sends conversion events back to Google. Use it to compare campaign cost with funnel revenue and feed better conversion data to Google Ads.

## What This Integration Provides

<CardGroup>
  <Card title="Conversion Tracking" icon="arrow-trend-up">
    Automatically send conversion postbacks using Google Click ID (gclid) for accurate attribution
  </Card>

  <Card title="Ad Spend Syncing" icon="dollar-sign">
    Automatically import your daily ad spend, clicks, and impressions for accurate ROI reporting
  </Card>

  <Card title="Campaign Management" icon="sliders">
    Sync campaign data, update status, and manage budgets directly from ElasticFunnels
  </Card>

  <Card title="Tracking Link Builder" icon="link">
    Generate UTM parameters with Google Ads format for proper attribution
  </Card>
</CardGroup>

## Setup Guide

### Step 1: Connect Your Google Ads Account

1. Navigate to **Settings → Integrations → Advertising**
2. Find **Google Ads** and click **"New integration"** or **"Manage integrations"**
3. Click **"Connect your Google Ads Account"**
4. You'll be redirected to Google to authorize access
5. Sign in with the Google account that has access to your Google Ads account
6. On the permission screen, **leave every box ticked**, including the Google Ads box

<Warning>
  **Do not untick the Google Ads permission.** Google's consent screen lets you approve the sign-in while refusing the Google Ads permission, and the connection still completes. It looks connected, but no ad accounts can be read and no spend imports. See [Connection and Permissions](#connection-and-permissions) for how to spot and fix this.
</Warning>

<Info>
  You'll need admin access to your Google Ads account to complete the authorization. A Google Ads Developer Token must be configured at the application level (contact support if needed).
</Info>

### Step 2: Select Your Ad Account

After authorization, you'll see a list of all Google Ads accounts you have access to:

1. Review the available accounts (shown with account ID and name)
2. Select the account you want to track
3. The selected account will be saved to your integration

<Tip>
  If you manage multiple businesses, you can create separate integrations for each Google Ads account to keep reporting organized.
</Tip>

If the list comes back empty or shows a red error box, the connection has a problem that selecting an account will not fix. Read [When No Ad Accounts Appear](#when-no-ad-accounts-appear).

### Step 3: Configure Conversion Tracking (Required for Postbacks)

To enable conversion postbacks (highly recommended):

1. **Enter your Conversion Action ID**
   * Find it in Google Ads → Tools & Settings → Conversions
   * Create a new conversion action if you don't have one
   * Copy the Conversion Action ID (numeric value)

2. **Enable Conversion Postbacks**
   * Check the box to enable automatic postback sending
   * This sends purchase data back to Google Ads when customers complete orders

3. Click **"Update Integration"** to save

<Warning>
  Conversion postbacks require a valid Conversion Action ID. If you enable postbacks without a Conversion Action ID, the system will warn you. The postback will only fire when conversions have a valid gclid (Google Click ID) parameter.
</Warning>

## Connection and Permissions

### Which Google Account Is Connected

The integration stores credentials for one Google account, and that account is not always the person who set it up. An agency staffer, a former employee, or a personal Gmail can end up holding the connection.

Open the integration and look at the **Connected Google Account** card at the top. It shows:

* The email address of the Google account that authorized the connection
* The account name, when Google returns one different from the email
* The date the connection was made

<Tip>
  Check this card first whenever spend stops importing. If the email is not the account you expect, the connection is reading a different set of Google Ads accounts than you think.
</Tip>

If the card says the account has not been recorded yet, the integration was connected before this was tracked. Click **Reconnect** and the email will be filled in.

### The Google Ads Permission

The connection asks Google for three things: your email, your basic profile, and access to Google Ads. Only the third one lets ElasticFunnels read campaigns and spend.

Google's consent screen shows these as separate tick boxes. Approving the sign-in while unticking the Google Ads box produces a working set of credentials with no Google Ads access. The connection saves and reports success. Every later request to Google Ads is refused.

When this happens the integration shows a red banner:

> **Google Ads permission was not granted.** This account is signed in, but it did not approve access to Google Ads, so no ad accounts can be read and spend will not import. Reconnect and leave the Google Ads box ticked on the consent screen.

The fix is to reconnect and approve the Google Ads permission.

### Reconnecting an Integration

Use the **Reconnect** button on the integration you want to fix, not the generic connect button on the Advertising tab.

The Reconnect button names the integration it belongs to, so the new credentials replace that integration's credentials. Starting a fresh connect flow on a brand that already has several Google Ads integrations can write the new credentials onto a different one.

<Info>
  Reconnecting always shows Google's permission screen again, even for an account you have already approved. This is deliberate. It is the only way to grant a permission you previously refused.
</Info>

Reconnecting keeps your selected ad account, Conversion Action ID, and postback settings. It replaces only the credentials.

## When No Ad Accounts Appear

An empty ad account list is a symptom, not a cause. The integration reports what Google actually said, so read the message shown in the red box rather than guessing.

| What the integration shows | What it means | What to do |
| - | - | - |
| **No Google account is connected** | The integration row exists but no connect flow ever finished. | Click **Connect your Google Ads Account**. |
| **Google refused access to Google Ads for this account** | The credentials are valid, but they lack the Google Ads permission. | Reconnect and leave the Google Ads box ticked. |
| **Access to this Google account was revoked** | Someone removed ElasticFunnels in their Google account security settings, or the password changed. | Reconnect. |
| **Could not sign in to Google with the stored credentials** | Google rejected the stored credentials when refreshing them. | Reconnect. |
| **Google rejected the stored credentials** | The credentials are no longer accepted. | Reconnect. |
| **The Google Ads API version in use has been retired** | A platform-level problem, not an account problem. | Contact support. Reconnecting will not help. |
| **No ad accounts found** with no error | Google answered normally and the account genuinely has no Google Ads accounts. | Confirm the connected email has access to a Google Ads account. |

<Warning>
  The most common cause of a silently broken Google Ads integration is the refused Google Ads permission. It is easy to miss because the connection reports success, the integration looks configured, and the only symptom is that no data ever arrives.
</Warning>

## Understanding Google Click ID (gclid)

### How It Works

Google Ads uses **gclid** (Google Click ID) to track which clicks lead to conversions:

1. When someone clicks your Google Ads link, Google adds a `gclid` parameter to the URL
2. ElasticFunnels automatically captures this `gclid` in the click tracking data
3. When a conversion occurs, we send the `gclid` back to Google Ads
4. Google Ads attributes the conversion to the original click

### Why This Matters

```
Example: Conversion Attribution

User clicks Google Ad → URL includes gclid=abc123
User visits your funnel → gclid is captured
User makes purchase → Conversion postback sent with gclid=abc123
Google Ads → Attributes conversion to original click
```

<Check>
  The gclid is automatically captured when users click Google Ads links. You don't need to manually configure anything - just ensure you're using Google Ads tracking links.
</Check>

## Ad Spend Syncing

### Automatic Sync Schedule

Your ad spend data syncs automatically on a regular schedule. This includes:

* Daily spend amounts
* Click counts
* Impression counts
* Campaign names
* Ad group information

<Note>
  Historical data is available immediately after connecting. Future data syncs automatically without any action needed.
</Note>

### Viewing Your Ad Data

After your first sync completes, you can view your ad performance:

1. Go to **Analytics → Ad Spend Reports**
2. Select your date range
3. View spend, clicks, and ROI metrics
4. Filter by campaign, ad group, or specific ads

## Conversion Postbacks

### What Are Conversion Postbacks?

Conversion postbacks send purchase information back to Google Ads when a customer completes an order. This helps Google Ads:

* Optimize your campaigns for conversions (not just clicks)
* Improve audience targeting based on who actually buys
* Provide accurate attribution data
* Enable features like automated bidding

### What Data is Sent

When a conversion occurs, we send:

* Purchase event
* Order value and currency
* Order ID
* Google Click ID (gclid)
* Conversion Action ID

<Info>
  All customer data is handled according to Google's privacy requirements. Conversion data is sent securely to Google Ads.
</Info>

### When Postbacks Are Triggered

Postbacks fire automatically when:

1. ✅ Customer clicked a Google Ad (gclid present in click data)
2. ✅ Customer completed a purchase
3. ✅ Integration has postbacks enabled
4. ✅ Conversion Action ID is configured

<Warning>
  If a conversion doesn't have a gclid (e.g., user didn't come from Google Ads), no postback will be sent. This is expected behavior.
</Warning>

## Tracking Link Builder Integration

The Tracking Link Builder automatically generates the correct UTM parameters for Google Ads:

**Google Ads Template:**

```
utm_source=google
utm_medium=cpc
utm_campaign={campaignid}
utm_term={keyword}
utm_content={creative}
adid=ga_{creative}_{campaignid}
```

<Info>
  Access the Tracking Link Builder from **Tools → Tracking → Tracking Link Builder** or from the Pages/Funnels list dropdown menu.
</Info>

## Campaign Management

Go to **Reports → Ad Campaigns** in the sidebar and pick your Google Ads integration to browse the account:

* Campaigns, with spend, clicks, and impressions for a date range you choose
* Ad groups inside each campaign
* Ads inside each ad group, including headlines and descriptions
* Funnel revenue and profit next to the ad metrics, when your tracking links carry the right parameters

The status column accounts for parents. An ad group that is enabled inside a paused campaign reads as **Active but campaign paused**, so you can tell the difference between an ad group you paused and one that cannot deliver because of the campaign above it.

See the [Campaigns Management](/integrations/campaigns-management) guide for the full interface, metric definitions, and the tracking link requirements that make funnel metrics appear.

## Managing Multiple Integrations

If you manage multiple businesses or clients, you can create multiple Google Ads integrations:

### When to Create Multiple Integrations

* Managing different client accounts (agencies)
* Separate businesses with different Google Ads accounts
* Different brands under one ElasticFunnels account
* Testing vs. production campaigns

### How It Works

Each integration is independent:

* Has its own Google Ads account
* Has its own Conversion Action ID
* Has its own postback settings
* Syncs separately

<Tip>
  Name each integration clearly (e.g., "Client A - Supplements", "Client B - Software") to keep them organized.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No Data Appearing After Setup">
    **Possible Causes:**

    * The Google Ads permission was refused on the consent screen (most common)
    * First sync hasn't run yet
    * No ad spend in the selected date range
    * Ad account has no active campaigns

    **Solution:** Open the integration and check the **Connected Google Account** card. If a red permission banner is showing, reconnect and leave the Google Ads box ticked. Otherwise wait for the first sync, or contact support to trigger a manual sync.
  </Accordion>

  <Accordion title="Ad Account List Is Empty">
    **Cause:** Almost always a credentials or permission problem rather than a missing account.

    **Solution:** Read the message in the red box on the integration and match it against the table in [When No Ad Accounts Appear](#when-no-ad-accounts-appear). Most cases are fixed by reconnecting.
  </Accordion>

  <Accordion title="Wrong Google Account Is Connected">
    **Cause:** The connection was made by someone else, or with a different Google login than intended. Agencies hit this when a staff member connects with their own account.

    **Solution:** Check the email on the **Connected Google Account** card. Click **Reconnect**, sign in as the correct Google account, and approve the Google Ads permission. Your ad account selection and postback settings are kept.
  </Accordion>

  <Accordion title="Session Expired / Connection Error">
    **Cause:** The stored Google credentials stopped working. This happens when the permission is removed in the Google account's security settings, when the password changes, or when Google revokes access.

    **Solution:** Click **Reconnect** on your integration and approve the Google Ads permission again.
  </Accordion>

  <Accordion title="An Ad Group or Ad Shows Active but Gets No Traffic">
    **Cause:** A parent is paused. An enabled ad group inside a paused campaign cannot deliver, and neither can an enabled ad inside a paused ad group.

    **Solution:** The status column names the reason, for example **Active but campaign paused**. Activate the parent, or accept that the child will not run until you do.
  </Accordion>

  <Accordion title="Conversions Not Showing in Google Ads">
    **Possible Causes:**

    * Postbacks not enabled
    * No Conversion Action ID configured
    * Customer didn't click a Google Ad (no gclid)
    * gclid expired (Google Ads has a 90-day attribution window)

    **Solution:**

    1. Verify Conversion Action ID is entered correctly
    2. Check "Enable Conversion Postbacks" is checked
    3. Ensure customers are clicking Google Ads links (gclid must be present)
  </Accordion>

  <Accordion title="What is a Developer Token?">
    **Answer:** A Developer Token is required for Google Ads API access. It's configured at the application level by ElasticFunnels support, not per integration. If you see errors about Developer Token, contact support.
  </Accordion>
</AccordionGroup>

## Best Practices

<Steps>
  <Step title="Set Up Conversion Postbacks">
    Always enable postbacks to help Google Ads optimize your campaigns for actual purchases, not just clicks.
  </Step>

  <Step title="Use Tracking Link Builder">
    Always use the Tracking Link Builder when creating Google Ads links to ensure proper gclid tracking and UTM parameters.
  </Step>

  <Step title="Configure Conversion Action">
    Set up a conversion action in Google Ads before enabling postbacks. Use a meaningful name like "Purchase" or "Lead Form Submission".
  </Step>

  <Step title="Monitor Postback Success">
    Check your integration status regularly to ensure postbacks are being sent successfully.
  </Step>
</Steps>

## Required Information

* Google Ads account access with admin permissions
* A Google login that approves the Google Ads permission during authorization
* Conversion Action ID (created in Google Ads)
* Google Ads Developer Token (configured at application level)

## Benefits of Integration

* **Conversion Tracking**: Measure which keywords and ads drive conversions
* **Smart Bidding**: Use conversion data for automated bidding strategies
* **Audience Insights**: Better understand your converting audience
* **ROI Measurement**: Calculate exact return on ad spend
* **Campaign Optimization**: Google Ads uses conversion data to improve targeting

## Next Steps

<CardGroup>
  <Card title="View Ad Reports" icon="chart-line" href="/analytics/ad-spend">
    See your ad performance and ROI metrics
  </Card>

  <Card title="Meta Ads Integration" icon="rectangle-ad" href="/integrations/meta-ads">
    Connect Meta Ads for complete cross-platform tracking
  </Card>

  <Card title="Tracking Link Builder" icon="link" href="/integrations/affiliate-tracking#tracking-link-builder">
    Create properly formatted tracking URLs
  </Card>

  <Card title="Analytics Dashboard" icon="chart-mixed" href="/analytics/overview">
    Unified view of all your marketing metrics
  </Card>
</CardGroup>


# Google Analytics Integration
Source: https://docs.elasticfunnels.io/integrations/google-analytics

Connect Google Analytics 4 (GA4) for traffic, behavior, and attribution data

## Overview

Google Analytics integration sends page and conversion data to Google Analytics 4 (GA4). You can set measurement IDs per page when different funnels or campaigns need different GA4 properties.

## What This Integration Provides

<CardGroup>
  <Card title="Page-Level Tracking" icon="file-text">
    Configure different GA4 Measurement IDs for each page, enabling flexible tracking across funnels
  </Card>

  <Card title="Automatic Page Views" icon="eye">
    Page views are tracked automatically when pages load - no manual configuration needed
  </Card>

  <Card title="Custom Event Tracking" icon="code">
    Track custom events through page interactions (button clicks, form submissions, etc.)
  </Card>

  <Card title="Multi-Touch Attribution" icon="sitemap">
    Integrates with pixel attribution system for accurate conversion attribution across multiple pages
  </Card>
</CardGroup>

## Setup Guide

### Step 1: Find Your Measurement ID

Your Measurement ID can be found in your Google Analytics account:

1. Go to **Admin → Property Settings** in Google Analytics
2. Look for **"Measurement ID"** (starts with `G-` for GA4)
3. Copy the entire ID including the `G-` prefix

<Info>
  The Measurement ID format is `G-XXXXXXXXXX` where X is alphanumeric. Make sure to copy the entire ID including the `G-` prefix.
</Info>

### Step 2: Configure Measurement ID

You can configure Google Analytics at two levels:

<AccordionGroup>
  <Accordion title="Page-Level Configuration (Recommended)">
    Set a Measurement ID for each individual page in your funnel.

    **How to:**

    1. Go to **Pages** in the main menu
    2. Edit the page you want to track
    3. Find the **Google Analytics** section in page settings
    4. Enter your Measurement ID (format: `G-XXXXXXXXXX`)
    5. Save the page

    **Best for:** Different funnels, brands, or campaigns that need separate GA4 properties
  </Accordion>

  <Accordion title="Global Script Configuration (Alternative)">
    Configure a global tracking script that applies to all pages.

    **How to:**

    1. Go to **Settings → Tracking Scripts**
    2. Add a new tracking script
    3. Select **Google Analytics** as the script type
    4. Enter your Measurement ID
    5. Save the script

    **Best for:** Single brand with one GA4 property for all pages
  </Accordion>
</AccordionGroup>

<Tip>
  Page-level configuration gives you more flexibility. You can use different GA4 properties for different funnels, brands, or campaigns, enabling better segmentation and reporting.
</Tip>

## How It Works

### Automatic Page View Tracking

When a page loads with a configured Measurement ID:

1. The GA4 tracking script is automatically injected
2. A page view event is sent to Google Analytics
3. The Measurement ID is captured in the pixel attribution system
4. User behavior and traffic sources are tracked

<Check>
  Page views are tracked automatically - you don't need to add any tracking code manually. Just configure the Measurement ID and it works.
</Check>

### Pixel Attribution Integration

Google Analytics Measurement IDs are integrated with the pixel attribution system:

* Enables multi-touch attribution across multiple pages
* Works with conversion postbacks for advertising platforms
* Supports accurate conversion attribution

<Info>
  The pixel attribution system tracks which GA4 properties a visitor was exposed to, enabling accurate multi-touch conversion attribution.
</Info>

## Custom Event Tracking

### Setting Up Custom Events

You can track custom events through page interactions:

1. **In Page Builder:**
   * Add an interaction to a button, link, or element
   * Select **"Custom GA Event"** as the interaction type
   * Configure the event name and parameters

2. **Event Parameters:**
   * Event name (required)
   * Event category (optional)
   * Event label (optional)
   * Event value (optional)

### Example Custom Events

Track important user actions:

* **Form Submissions:** Track when users submit lead forms
* **Button Clicks:** Track clicks on important CTAs
* **Video Plays:** Track video engagement
* **Scroll Depth:** Track how far users scroll
* **Time on Page:** Track engagement duration

<Note>
  Custom events appear in Google Analytics Real-Time reports within seconds.
</Note>

## What You'll Track

* **Page Views**: See which pages get the most traffic
* **User Behavior**: Understand how visitors navigate your funnel
* **Traffic Sources**: Identify your best-performing channels
* **Conversion Paths**: See the complete customer journey
* **Demographic Data**: Learn about your audience demographics
* **Custom Events**: Track specific user interactions
* **Multi-Touch Attribution**: See which pages contributed to conversions

## Integration with Conversion Postbacks

Google Analytics integrates with the conversion postback system:

* GA4 Measurement IDs are captured when visitors view pages
* When conversions occur, the system knows which GA4 properties were viewed
* This enables accurate attribution for advertising platforms
* Supports multi-touch attribution across the customer journey

<Info>
  The integration can run alongside Meta Ads, Google Ads, and other ad platforms so each tool receives the conversion data it needs.
</Info>

## Advanced Setup

### Custom Events Configuration

Configure custom events for specific actions:

1. Use the page builder to add interactions
2. Select "Custom GA Event" interaction type
3. Configure event name and parameters
4. Test in GA4 Real-Time reports

### Conversion Goals

Set up conversion goals in Google Analytics:

1. Go to **Admin → Events** in Google Analytics
2. Mark important events as conversions
3. Configure conversion values if applicable
4. View conversions in GA4 reports

### Custom Audiences

Create custom audiences for remarketing:

1. Use GA4 audience builder
2. Define audience criteria
3. Use audiences in Google Ads campaigns
4. Track audience performance

## Best Practices

<Steps>
  <Step title="Use Page-Level Configuration">
    Configure Measurement IDs at the page level for maximum flexibility. This allows different funnels to use different GA4 properties.
  </Step>

  <Step title="Set Up Custom Events">
    Track important user actions (form submissions, button clicks) using custom events to understand user engagement.
  </Step>

  <Step title="Test Event Tracking">
    After setting up custom events, test them in GA4 Real-Time reports to verify they're working correctly.
  </Step>

  <Step title="Use Consistent Naming">
    Use consistent event names and parameters across your funnel for easier reporting and analysis.
  </Step>

  <Step title="Monitor Attribution">
    Use the pixel attribution system to understand which pages contribute to conversions for multi-touch attribution.
  </Step>
</Steps>

## Tips for Better Analytics

* **Set up goal funnels** to identify drop-off points in your conversion process
* **Use UTM parameters** to track campaign performance (see [Tracking Link Builder](/integrations/affiliate-tracking#tracking-link-builder))
* **Create custom dashboards** in GA4 for quick insights
* **Regular data review** and analysis for optimization opportunities
* **Use separate GA4 properties** for different brands or campaigns when needed
* **Test custom events** in Real-Time reports before relying on them

## Troubleshooting

<AccordionGroup>
  <Accordion title="Page Views Not Showing in GA4">
    **Possible Causes:**

    * Measurement ID not configured on the page
    * Incorrect Measurement ID format (must include G- prefix)
    * GA4 property not receiving data

    **Solution:**

    1. Verify Measurement ID is entered correctly (format: `G-XXXXXXXXXX`)
    2. Check page settings to ensure Measurement ID is saved
    3. Test in GA4 Real-Time reports
  </Accordion>

  <Accordion title="Custom Events Not Tracking">
    **Possible Causes:**

    * Event not configured correctly in page builder
    * Event name contains invalid characters
    * GA4 property not receiving events

    **Solution:**

    1. Verify event is configured in page interactions
    2. Check event name format (alphanumeric, underscores, hyphens only)
    3. Test in GA4 Real-Time reports
  </Accordion>

  <Accordion title="Different Pages Need Different GA4 Properties">
    **Answer:** Yes! Configure Measurement IDs at the page level. Each page can have its own GA4 Measurement ID, allowing you to use different GA4 properties for different funnels or brands.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Tracking Link Builder" icon="link" href="/integrations/affiliate-tracking#tracking-link-builder">
    Create properly formatted tracking URLs with UTM parameters
  </Card>

  <Card title="Analytics Dashboard" icon="chart-mixed" href="/analytics/overview">
    View analytics and conversion data
  </Card>

  <Card title="Conversion Tracking" icon="bullseye-arrow" href="/analytics/conversions">
    Deep dive into your conversion data and attribution
  </Card>

  <Card title="Meta Ads Integration" icon="rectangle-ad" href="/integrations/meta-ads">
    Connect Meta Ads for advertising platform integration
  </Card>
</CardGroup>


# Google Sheets Integration
Source: https://docs.elasticfunnels.io/integrations/google-sheets

Read and write rows in Google Sheets from ElasticFunnels automations using OAuth or a service account.

## Overview

The Google Sheets integration gives ElasticFunnels automations full read/write access to a spreadsheet. Use it for ad-hoc lead tracking, data offload to ops teams who live in spreadsheets, or as a temporary store before more permanent reporting is built.

## What you can do

| Action | What it does |
| - | - |
| Append row | Adds a row to the bottom of a sheet |
| Batch update | Updates multiple cells in a single API call |
| Read values | Reads a range of cells (single sheet or multiple) |
| Find row | Looks up a row by a search value, returns the row data and index |
| Update row by search | Updates a row matched by a search value (upsert-style) |
| Create sheet | Adds a new tab to an existing spreadsheet |
| Clear range | Empties a range without removing formatting |

The integration uses **Google Sheets API v4** and respects the published 300-requests-per-minute quota with built-in throttling and retry.

## Setup

You can authenticate two ways. Pick whichever matches how your team manages Google access.

### Option A — OAuth (one user)

<Steps>
  <Step title="Connect your Google account">
    Go to **Integrations** → **Storage** → **Google Sheets** → **Connect with Google**. EF redirects you to Google's OAuth screen.
  </Step>

  <Step title="Grant Sheets access">
    Tick the **See, edit, create, and delete your spreadsheets** scope. EF stores an OAuth refresh token so it can keep accessing your sheets without re-prompting you.
  </Step>

  <Step title="Pick a default spreadsheet (optional)">
    The form lets you pre-pick a spreadsheet so you don't have to paste the ID every time you build an automation.
  </Step>
</Steps>

### Option B — Service account (recommended for teams)

<Steps>
  <Step title="Create a service account">
    In the Google Cloud Console, create a project, enable the **Google Sheets API**, and create a **service account** with no roles. Generate a JSON key and download it.
  </Step>

  <Step title="Share your spreadsheet with the service account">
    Open each spreadsheet you want EF to access and **Share** it with the service account's email (looks like `xxx@xxx.iam.gserviceaccount.com`) as **Editor**.
  </Step>

  <Step title="Paste the JSON in EF">
    Paste the full JSON key contents into the **Service Account JSON** field of the EF integration form. Save.
  </Step>
</Steps>

<Tip>
  **Use a service account in production.** OAuth tokens are tied to a specific Google user — if that person leaves your org, the integration breaks. A service account belongs to your project, not a person.
</Tip>

## Patterns

### Lead handoff to sales

Trigger: `Form: submitted` → Action: `Google Sheets: Append row` to a "New Leads" tab with `email`, `name`, `phone`, `source`, `submitted_at`. The sales team works the sheet directly without logging into EF.

### Order export for fulfillment ops

Trigger: `Conversion: purchase` → Action: `Google Sheets: Append row` to an "Orders" tab with one row per line item.

### Inventory check before purchase

Trigger: `Form: submitted` (pre-checkout) → Action: `Google Sheets: Find row` matching the SKU on an "Inventory" tab → Condition: `available > 0` → continue or redirect to a backorder page.

## Limits

* **300 requests / minute** per integration (Google's quota; throttle is built-in).
* **5 million cells** per spreadsheet (Google's hard limit). Move to a database before you get close.
* Cell values are coerced to strings on write unless the sheet column is pre-formatted as date / number / currency.

## Troubleshooting

<AccordionGroup>
  <Accordion title="403 forbidden when writing">
    The service account hasn't been added to the spreadsheet, or the OAuth account no longer has access. Re-share the file or re-authenticate.
  </Accordion>

  <Accordion title="429 rate limited">
    You're sending more than 300 requests / minute. Spread writes out (e.g. batch them with `Batch update` instead of one append per row), or split traffic across multiple spreadsheets.
  </Accordion>

  <Accordion title="Wrong cell type after append">
    Pre-format the destination column in the spreadsheet (Format → Number) so Google Sheets knows to interpret the value correctly.
  </Accordion>
</AccordionGroup>


# JVZoo Integration
Source: https://docs.elasticfunnels.io/integrations/jvzoo

Receive JVZoo affiliate postbacks and vendor IPNs to record sales, refunds, and chargebacks in ElasticFunnels.

## Overview

JVZoo has two postback flows. ElasticFunnels supports both, as separate integrations:

* **JVZoo Affiliate S2S** — Set up when you promote JVZoo offers as an affiliate. ElasticFunnels receives a postback for each commission so the affiliate sale is attributed back to the original ElasticFunnels click.
* **JVZoo Vendor IPN** — Set up when you sell **your own** offers through JVZoo checkout. ElasticFunnels receives the JVZoo Instant Payment Notification for every sale, rebill, refund, chargeback, and cancellation, and verifies it with your JVZoo `cverify` secret.

You can run both integrations side by side if you both vend on JVZoo and run affiliate traffic.

## JVZoo Affiliate S2S

### How it works

1. You promote a JVZoo offer using an ElasticFunnels click code in the `tid` parameter on your JVZoo affiliate link.
2. When a sale happens, JVZoo fires a server-to-server postback to your ElasticFunnels postback URL.
3. ElasticFunnels reads the macros and creates a conversion.

### Macros consumed

| Macro | Used as |
| - | - |
| `{tid}` | ElasticFunnels click code (used to attribute the sale) |
| `{transaction_id}` | External transaction ID stored on the conversion |
| `{affiliate_amount}` | Affiliate commission amount |
| `{customer_email}` | Customer email |
| `{product_title}` | Product name shown in ElasticFunnels reports |
| `{transaction_type}` | `purchase` or `refund` (mapped to EF conversion type) |

### Setup

<Steps>
  <Step title="Activate the integration">
    Go to **Integrations** → **Affiliate Networks** → **JVZoo Affiliate S2S** and click **Activate**.
  </Step>

  <Step title="Copy the postback URL">
    Copy the unique postback URL from the form.
  </Step>

  <Step title="Configure JVZoo">
    In your JVZoo affiliate dashboard, paste the postback URL into the affiliate notification settings for the offer(s) you promote. Make sure the link template includes `tid={{click_code}}` so the EF click code is sent back.
  </Step>

  <Step title="Test">
    Make a test purchase on the JVZoo offer. The conversion should appear in **Conversions** within seconds.
  </Step>
</Steps>

## JVZoo Vendor IPN

### How it works

JVZoo posts a `JVZIPN` payload to your IPN URL on every transaction event for products you vend. ElasticFunnels:

1. Verifies the payload using the `cverify` SHA-1 signature against your JVZoo secret key.
2. Parses both v1 and v2 payload formats.
3. Records the matching event:
   * `SALE` → `purchase`
   * `BILL` → `rebill`
   * `RFND` → `refund`
   * `CGBK` → `chargeback`
   * `CANCEL-REBILL` → `cancellation`
4. Attributes the conversion when the posted tracking ID matches an ElasticFunnels click code.

### Setup

<Steps>
  <Step title="Get your JVZoo secret key">
    In your JVZoo vendor account: **My Account** → **Seller Settings** → **Postbacks**. Copy the **Secret Key**.
  </Step>

  <Step title="Activate the integration">
    Go to **Integrations** → **Affiliate Networks** → **JVZoo Vendor IPN**. Paste the secret key and save.
  </Step>

  <Step title="Configure the IPN URL in JVZoo">
    Copy the **IPN URL** from the form and paste it into the JVZoo product's **Notify URL** field. Save the JVZoo product.
  </Step>

  <Step title="Use tracking IDs from EF">
    Build your buy links with `[BUY=...]` tags rather than hardcoding them. ElasticFunnels then passes the click code automatically as `vtid`, the vendor tracking parameter, and reads it back from the IPN to attribute the order. Hardcoded links carry no click code, so their sales arrive unattributed. See [JVZoo merchant setup](/merchants/jvzoo) for buy links, the funnel ID, and the sales pixel.
  </Step>

  <Step title="Test">
    Make a test purchase. The IPN should arrive within seconds; failed signature checks are logged with the reason so you can debug a key mismatch.
  </Step>
</Steps>

<Warning>
  **Don't share the secret key.** It's the only thing preventing third parties from forging IPN events. ElasticFunnels stores it encrypted and never exposes it in logs.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Affiliate postbacks not arriving">
    Check that JVZoo's affiliate notification URL exactly matches the EF postback URL (no trailing whitespace) and that your link template includes the `tid` parameter populated with the EF click code.
  </Accordion>

  <Accordion title="Vendor IPNs failing signature check">
    The JVZoo secret in EF must match the **current** secret in your JVZoo seller settings. If you regenerated the secret, paste the new value into the EF integration form. Failed `cverify` checks are recorded under **Logs** → **Inbound Postbacks** so you can see the exact reason.
  </Accordion>

  <Accordion title="Sales recorded with no click attribution">
    The JVZoo payload didn't include a tracking ID matching an EF click code. Audit your JVZoo links to ensure they carry the click code: `tid` when you are the affiliate, `vtid` when you are the vendor. Vendor buy links built from `[BUY=...]` tags set `vtid` for you; hardcoded links do not.
  </Accordion>
</AccordionGroup>


# Meta Ads Integration
Source: https://docs.elasticfunnels.io/integrations/meta-ads

Connect Facebook/Meta Ads to track ad performance, sync spend data, and send conversion postbacks

## Overview

The Meta Ads integration syncs ad spend into ElasticFunnels and sends conversion events back to Meta. Use it to compare campaign cost with funnel revenue and feed better conversion data to Meta.

## What This Integration Provides

<CardGroup>
  <Card title="Ad Spend Tracking" icon="dollar-sign">
    Automatically import your daily ad spend, clicks, and impressions for accurate ROI reporting
  </Card>

  <Card title="Conversion Postbacks" icon="arrow-trend-up">
    Send purchase data back to Meta to improve campaign optimization and attribution
  </Card>

  <Card title="Unified Reporting" icon="chart-mixed">
    See your ad performance alongside your funnel metrics in one dashboard
  </Card>

  <Card title="Multi-Account Support" icon="layer-group">
    Connect multiple ad accounts if you manage different businesses or campaigns
  </Card>
</CardGroup>

## Setup Guide

### Step 1: Connect Your Meta Ads Account

1. Navigate to **Settings → Integrations → Advertising**
2. Find **Meta Ads** and click **"New integration"** or **"Manage integrations"**
3. Click **"Connect your Meta Ads Account"**
4. You'll be redirected to Facebook to authorize access
5. Grant the necessary permissions for ad data access

<Info>
  You'll need admin access to your Meta Ads account to complete the authorization.
</Info>

### Step 2: Select Your Ad Account

After authorization, you'll see a list of all ad accounts you have access to:

1. Review the available accounts (shown with account ID, name, and currency)
2. Click **Select** next to the ad account you want to track
3. The selected account will be highlighted with a blue checkmark

<Tip>
  If you manage multiple businesses, you can create separate integrations for each ad account to keep reporting organized.
</Tip>

### Step 3: Configure Conversion Tracking (Optional)

To enable conversion postbacks (highly recommended):

1. **Enter your Meta Pixel ID**
   * Find it in Meta Business Manager → Events Manager → Data Sources
   * It's a 15-16 digit number

2. **Enable Conversion Postbacks**
   * Check the box to enable automatic postback sending
   * This sends purchase data back to Meta when customers complete orders

3. Click **"Update Integration"** to save

<Warning>
  Conversion postbacks require a valid Pixel ID. If you enable postbacks without a Pixel ID, the system will warn you.
</Warning>

## Understanding Pixel Attribution

### How It Works

ElasticFunnels uses a **page-based pixel tracking system** to ensure accurate attribution:

1. **Each page** in your funnel can have its own Meta Pixel ID
2. When a visitor lands on a page, we **track which pixels they were exposed to**
3. When they make a purchase, we **send conversion data to the correct pixel(s)**

### Why This Matters

```
Example: Multi-Business Scenario

Page 1 (Product A): Uses Pixel 111
Page 2 (Product B): Uses Pixel 222

If customer visits both pages and purchases:
→ Both Pixel 111 and Pixel 222 receive the conversion
→ Accurate attribution for partnership/referral funnels
```

### Setting Pixel ID per Page

You can configure the Meta Pixel ID at two levels:

<AccordionGroup>
  <Accordion title="Integration Level (Recommended for Single Business)">
    Set one Pixel ID in the integration settings. This pixel will receive conversions from any page the customer visited during their journey.

    **Best for:** Single business with one website
  </Accordion>

  <Accordion title="Page Level (Advanced Multi-Business)">
    Set different Pixel IDs on individual pages in your funnel settings. This allows different businesses or partners to track their own conversions.

    **Best for:** Agency managing multiple clients, partnership funnels
  </Accordion>
</AccordionGroup>

## Ad Spend Syncing

### Automatic Sync Schedule

Your ad spend data syncs automatically **every 2 hours**. This includes:

* Daily spend amounts
* Click counts
* Impression counts
* Campaign names
* Ad set information

<Note>
  Historical data is available immediately after connecting. Future data syncs automatically without any action needed.
</Note>

### Viewing Your Ad Data

After your first sync completes, you can view your ad performance:

1. Go to **Analytics → Ad Spend Reports**
2. Select your date range
3. View spend, clicks, and ROI metrics
4. Filter by campaign, ad set, or specific ads

## Conversion Postbacks

### What Are Conversion Postbacks?

Conversion postbacks send purchase information back to Meta when a customer completes an order. This helps Meta:

* Optimize your campaigns for conversions (not just clicks)
* Improve audience targeting based on who actually buys
* Provide accurate attribution data
* Enable features like automated bidding

### What Data is Sent

When a conversion occurs, we send:

* Purchase event
* Order value and currency
* Order ID
* Customer information (hashed for privacy)
* Click identifier (fbclid)

<Info>
  All customer data is hashed and encrypted according to Meta's privacy requirements. We never send raw personal information.
</Info>

### When Postbacks Are Triggered

Postbacks fire automatically when:

1. ✅ Customer clicked a Meta ad (fbclid present)
2. ✅ Customer visited a page with a Meta Pixel
3. ✅ Customer completed a purchase
4. ✅ Integration has postbacks enabled
5. ✅ Pixel ID matches the page they visited

<Check>
  The system intelligently determines which pixel to fire based on which pages the customer visited. If they saw multiple pixels, all relevant pixels receive the conversion.
</Check>

## Managing Multiple Integrations

If you manage multiple businesses or clients, you can create multiple Meta Ads integrations:

### When to Create Multiple Integrations

* Managing different client accounts (agencies)
* Separate businesses with different websites
* Different brands under one ElasticFunnels account
* Testing vs. production campaigns

### How It Works

Each integration is independent:

* Has its own ad account
* Has its own Pixel ID
* Has its own postback settings
* Syncs separately

<Tip>
  Name each integration clearly (e.g., "Client A - Supplements", "Client B - Software") to keep them organized.
</Tip>

## Connection Status & Health

### Status Indicators

Your integration status shows real-time health:

* **🟢 Active** - Integration is working, data syncing normally
* **🔵 Syncing...** - Currently pulling new data from Meta
* **🔴 Error** - Connection issue that needs attention
* **⚪ Not Configured** - Integration not fully set up

### Last Sync Information

The integration card shows:

* **Last synced:** How long ago data was last updated
* **Records synced:** Number of records imported
* **Total spend:** Recent spending tracked

### Testing Your Connection

Use the **"Test Connection"** button to verify:

* Your access token is valid
* You have permission to access the ad account
* Data can be retrieved successfully

<Warning>
  If you see an error status, check if your Meta session has expired. Click the re-authenticate button to refresh your connection.
</Warning>

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="No Data Appearing After Setup">
    **Possible Causes:**

    * First sync hasn't run yet (syncs every 2 hours)
    * No ad spend in the selected date range
    * Ad account has no active campaigns

    **Solution:** Wait 2 hours for first sync, or contact support to trigger manual sync
  </Accordion>

  <Accordion title="Session Expired / Connection Error">
    **Cause:** Meta access tokens expire after 60 days

    **Solution:** Click the blue "Re-authenticate" button on your integration to refresh your connection
  </Accordion>

  <Accordion title="Conversions Not Showing in Meta">
    **Possible Causes:**

    * Postbacks not enabled
    * No Pixel ID configured
    * Customer didn't visit a page with your pixel

    **Solution:**

    1. Verify Pixel ID is entered correctly
    2. Check "Enable Conversion Postbacks" is checked
    3. Ensure your funnel pages have pixel configured
  </Accordion>

  <Accordion title="Multiple Ad Accounts - Which to Choose?">
    **Question:** I have 5 ad accounts listed, which should I select?

    **Answer:** Select the ad account that contains the campaigns you want to track. You can create multiple integrations if you need to track multiple ad accounts.
  </Accordion>

  <Accordion title="Pixel ID vs Ad Account - What's the Difference?">
    **Pixel ID:** Tracking code on your website (one per business/website)

    **Ad Account:** Where you manage your ad campaigns in Meta

    **Relationship:** Multiple ad accounts can share one pixel if they're promoting the same website.
  </Accordion>
</AccordionGroup>

### Getting Help

If you encounter issues:

1. Check the **Status** indicator on your integration
2. Click **"Test Connection"** to diagnose issues
3. Review the error message if one is shown
4. Contact support with your integration ID

## Best Practices

### Optimization Tips

<Steps>
  <Step title="Set Up Conversion Postbacks">
    Always enable postbacks to help Meta optimize your campaigns for actual purchases, not just clicks.
  </Step>

  <Step title="Use Descriptive Names">
    Name your integrations clearly, especially if managing multiple accounts (e.g., "Main Campaign - US", "Testing Account").
  </Step>

  <Step title="Monitor Sync Status">
    Check your integration status regularly to ensure data is syncing properly and connections haven't expired.
  </Step>

  <Step title="Test After Setup">
    Use the "Test Connection" button after setup to verify everything is working before running campaigns.
  </Step>
</Steps>

### Pixel Configuration Strategy

**Single Business:**

* Use ONE Pixel ID in your integration
* Apply to all funnel pages
* Simplest setup for most users

**Multi-Business or Agency:**

* Create SEPARATE integrations for each client
* Each integration gets its own Pixel ID
* Keeps reporting and postbacks isolated

**Partnership Funnels:**

* Set different Pixel IDs on different pages
* Partner pages fire partner's pixel
* Main pages fire your pixel
* Both get conversion credit

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="How often does ad spend data sync?">
    Every 2 hours automatically. Your data is always up-to-date without manual work.
  </Accordion>

  <Accordion title="Can I connect multiple Meta Ads accounts?">
    Yes! Click "Manage integrations" and then "Add integration" to connect additional accounts. Perfect for agencies or users managing multiple businesses.
  </Accordion>

  <Accordion title="Do I need a Pixel ID to use this integration?">
    No, Pixel ID is optional. It's only required if you want to send conversion postbacks to Meta. You can still sync and view ad spend data without it.
  </Accordion>

  <Accordion title="Will this affect my existing Meta Pixel setup?">
    No. This integration works alongside your existing pixel. It sends server-side conversion events that complement your pixel tracking.
  </Accordion>

  <Accordion title="How long until I see results in Meta?">
    Conversion postbacks appear in Meta Events Manager within 5-10 minutes. Ad spend data appears in ElasticFunnels within 2 hours of your first sync.
  </Accordion>

  <Accordion title="What if I manage campaigns for different clients?">
    Create separate integrations for each client. Each integration can have:

    * Different ad account
    * Different Pixel ID
    * Independent postback settings

    This keeps your client data properly separated.
  </Accordion>
</AccordionGroup>

## Data Privacy & Security

### What Data We Access

When you connect Meta Ads, we request permission to:

* Read your ad account information
* Access ad performance metrics (spend, clicks, impressions)
* View campaign and ad set names
* No access to modify or create ads

### How We Store Your Data

* Access tokens are encrypted and stored securely
* Ad spend data is stored for historical reporting
* Conversion data is hashed before sending to Meta
* You can disconnect at any time and data will be removed

### Compliance

Our integration follows:

* Meta's Platform Terms and Developer Policies
* GDPR and privacy regulations
* Secure OAuth 2.0 authentication
* Industry-standard encryption

## Next Steps

<CardGroup>
  <Card title="View Ad Reports" icon="chart-line" href="/analytics/ad-spend">
    See your ad performance and ROI metrics
  </Card>

  <Card title="Google Ads Integration" icon="rectangle-ad" href="/integrations/google-ads">
    Connect Google Ads for complete cross-platform tracking
  </Card>

  <Card title="Analytics Dashboard" icon="chart-mixed" href="/analytics/overview">
    Unified view of all your marketing metrics
  </Card>

  <Card title="Conversion Tracking" icon="bullseye-arrow" href="/analytics/conversions">
    Deep dive into your conversion data and attribution
  </Card>
</CardGroup>


# RedTrack Integration
Source: https://docs.elasticfunnels.io/integrations/redtrack

Send purchase, refund, and chargeback postbacks to RedTrack for accurate ad-traffic attribution.

## Overview

RedTrack is an ad tracker and conversion attribution platform for media buyers. The ElasticFunnels integration is **outbound only** — when a conversion is recorded in EF, a server-to-server postback is sent to RedTrack so the original click, traffic source, and campaign get the conversion credit.

## How it works

1. The visitor clicks a RedTrack tracking link. RedTrack appends a click ID (commonly `rtkclickid` or `clickid`, optionally inside a `sub` parameter you choose).
2. The visitor lands on an EF page. EF captures the click ID into the click record.
3. When EF later records a `purchase`, `refund`, or `chargeback`, it builds the RedTrack postback URL with the captured click ID and sends an HTTP GET.
4. RedTrack ingests the conversion event and attributes it to the original campaign.

## What we send

The postback URL template can use any of the following macros:

| Macro | Replaced with |
| - | - |
| `{clickid}` | RedTrack click ID (from `rtkclickid`, `clickid`, or your configured sub) |
| `{sum}` / `{amount}` | Conversion amount in your account currency |
| `{currency}` | ISO currency code (e.g. `USD`) |
| `{type}` | Event type (`purchase`, `refund`, `chargeback`) |
| `{order_id}` | EF conversion code |
| `{email}` | Customer email (optional) |

The default URL produced when you click **Insert sample URL** includes `{clickid}`, `{sum}`, `{currency}`, `{type}`, and `{order_id}`. Add custom parameters with the parameter builder if RedTrack expects more fields.

## Setup

<Steps>
  <Step title="Get your RedTrack postback URL">
    Log into RedTrack. Open the campaign settings → **Postback URL**. RedTrack will give you a URL template that already includes the macros it expects.
  </Step>

  <Step title="Activate the integration in EF">
    Go to **Integrations** → **Affiliate Networks** → **RedTrack** and click **Activate**. (RedTrack supports multiple integrations — useful if you run separate networks or accounts.)
  </Step>

  <Step title="Paste the postback URL">
    Paste the URL into the **Postback URL** field. Add or remove macros using the parameter builder; the URL field stays in sync.
  </Step>

  <Step title="Pick the click-ID parameter">
    Choose which URL parameter on landing pages contains the RedTrack click ID. Common values: `rtkclickid`, `clickid`, `sub1`. EF falls back through these automatically if your selection isn't found.
  </Step>

  <Step title="Configure merchant filtering (optional)">
    Limit the integration to specific merchants if not every funnel should report into RedTrack.
  </Step>

  <Step title="Save and test">
    Click an actual RedTrack tracking link, complete a small purchase, and confirm the conversion appears in your RedTrack reports. Use **Logs → External Postbacks** to inspect the raw URL and response.
  </Step>
</Steps>

## Multiple integrations

You can create more than one RedTrack integration when you need to:

* Track different RedTrack accounts (e.g. agency vs. in-house).
* Use different postback templates per merchant or per offer.
* Run a `purchase` integration alongside a separate refund/chargeback integration.

Each integration evaluates independently. A conversion can fan out to all of them.

## Troubleshooting

<AccordionGroup>
  <Accordion title="No postbacks being sent">
    The conversion most likely has no captured click ID. Verify the customer landed via a RedTrack tracking link and that the **Click-ID Parameter** in the EF integration matches what RedTrack actually appends to the URL.
  </Accordion>

  <Accordion title="Postbacks sent but RedTrack shows nothing">
    Open the postback in **Logs → External Postbacks** and confirm:

    * The URL has the correct macros and your RedTrack tracker domain.
    * The HTTP response code is 200/204 (success).
    * The click ID value matches an active campaign in RedTrack.
  </Accordion>

  <Accordion title="Refund / chargeback events missing">
    Make sure your postback URL includes `{type}` (or your network's equivalent) so RedTrack can distinguish refunds and chargebacks from purchases.
  </Accordion>
</AccordionGroup>


# Shopify Order Sync
Source: https://docs.elasticfunnels.io/integrations/shopify-order-sync

Send ElasticFunnels orders to your Shopify store as paid orders for tax reporting, accounting and 3PL fulfillment

## Overview

Shopify Order Sync creates an order in your Shopify store for every purchase made through ElasticFunnels. You keep ElasticFunnels for the funnel and the checkout, and Shopify (with the 3PL apps connected to it) for shipping, tax records and accounting.

<CardGroup>
  <Card title="Paid orders, tagged" icon="receipt">
    Each order arrives marked paid and tagged `ElasticFunnels`, with the customer, both addresses, SKUs, shipping, tax and discount.
  </Card>

  <Card title="One order per funnel" icon="layer-group">
    Optional: the main sale and its upsells and downsells from one funnel session arrive as one Shopify order.
  </Card>

  <Card title="Refunds carried over" icon="rotate-left">
    A refund made in ElasticFunnels reaches the Shopify order, so a 3PL app stops shipping a cancelled order.
  </Card>

  <Card title="Your prices" icon="dollar-sign">
    The order shows what the customer paid in ElasticFunnels, whatever the price in your Shopify catalog.
  </Card>

  <Card title="Tracking comes back" icon="truck-fast">
    When Shopify or its 3PL app ships the order, the tracking number comes back to ElasticFunnels and the buyer gets a shipped email.
  </Card>
</CardGroup>

## Limits to know first

<Warning>
  * **One Shopify store per brand.** The Shopify integration can be added once per brand. To sync to a second store, use a second brand.
  * **Installed through the ElasticFunnels team.** ElasticFunnels is not listed in the Shopify App Store. Each brand connects through its own custom Shopify app, which our team sets up for you (see [Set up](#set-up)).
  * **Shopify stock is not reduced.** Order lines are custom line items matched by SKU. They are not linked to your Shopify products or variants, so Shopify does not lower its inventory count for these orders. Track stock in ElasticFunnels (the product's **Inventory** settings) or in your 3PL.
  * **No product import from Shopify.** ElasticFunnels does not read your Shopify catalog. Products are created in ElasticFunnels; they can be pushed to Shopify (see [Products in Shopify](#products-in-shopify)).
  * **Cancellations and refunds made in Shopify do not come back.** Cancelling or refunding an order in the Shopify admin does not refund it in ElasticFunnels. Refund in ElasticFunnels and the refund reaches Shopify. Only shipment tracking comes back from Shopify (see [Tracking back from Shopify](#tracking-back-from-shopify)).
</Warning>

## Set up

<Steps>
  <Step title="Ask the ElasticFunnels team for an install link">
    Send us your store's `.myshopify.com` address. We create the custom Shopify app for your brand and send you an install link. Once your store is connected, the same link is shown on the integration as **Shopify install link**.
  </Step>

  <Step title="Install the app in Shopify">
    Open the link while you are logged in to your Shopify admin and click **Install**. Your store then connects to ElasticFunnels on its own. Shopify asks you to approve access to orders, customers, products, draft orders, inventory, price rules and shipping.
  </Step>

  <Step title="Turn on order sync">
    In ElasticFunnels go to **Integrations**, open the **Operations** tab and open **Shopify**. Turn on **Sync orders to Shopify** and save.
  </Step>

  <Step title="Choose which orders go to the store (optional)">
    Under **Merchants**, pick **All merchants**, **Specific merchants (whitelist)** or **Exclude merchants (blacklist)**. Under **Affiliate Filtering**, you can do the same by affiliate ID.
  </Step>

  <Step title="Decide on merging (optional)">
    Set **Max wait (minutes)** to 0 to send every purchase as its own order, or above 0 to merge a funnel's purchases into one order. See [Merge the funnel into one order](#merge-the-funnel-into-one-order).
  </Step>

  <Step title="Test it">
    Turn on **Send test orders**, place a test purchase, then in Shopify go to **Orders** and filter by the tag `ElasticFunnels`. Turn **Send test orders** off again when you are done.
  </Step>
</Steps>

<Info>
  Once our team has set up the app for your brand, you can also connect from ElasticFunnels: open **Shopify**, enter **Your Shopify Store Domain**, turn on at least one option under **Integration Options** (for example **Sync orders to Shopify**), and click **Connect your Shopify Store**. If the app has not been set up yet you will see "Shopify app not set up". Contact us in that case.
</Info>

## Settings

These are on the **Shopify** card under **Integrations** → **Operations**. Everything below **Sync orders to Shopify** in this table appears only while it is on.

| Setting | What it does |
| - | - |
| **Sync orders to Shopify** | Sends ElasticFunnels purchases to this store. Merchant and affiliate filters apply while it is on. |
| **Send test orders** | Sends test orders to Shopify too. Off by default, so test orders stay out of your live store. |
| **Merge the funnel into one order**: **Max wait (minutes)** | 0 sends each purchase on its own (no merging). Above 0 turns merging on and is the longest an order waits after the first purchase of the session. Maximum 1440 (24 hours). New integrations start at 15. |
| **Merge the funnel into one order**: **Send early after quiet (minutes)** | Sends the merged order once no new purchase has come in for this long. Default 5. Must be lower than the max wait, otherwise every order waits the full max wait. |
| **Merchants** | All merchants, a whitelist, or a blacklist of merchants whose orders are sent. |
| **Affiliate Filtering** | All affiliates, a whitelist, or a blacklist of affiliate IDs whose orders are sent. |
| **Sync products** | Creates your ElasticFunnels products in Shopify. See [Products in Shopify](#products-in-shopify). |

The same card also has **Enable Shopify Checkouts** ([Shopify Checkout](/merchants/shopify-checkout)) and **Enable Shop Pay Merchant** ([Shop Pay](/merchants/shop-pay)), which use your store as a checkout instead.

## When orders are sent

With **Max wait (minutes)** at 0, each purchase is queued about 15 seconds after it completes and sent on the next sync run. The sync runs every minute, so the order usually appears in Shopify within a minute or two.

### Merge the funnel into one order

With **Max wait (minutes)** above 0, the main sale and the upsells and downsells bought in the same funnel session are held and sent to Shopify as **one** order. The order is sent at whichever comes first:

* no new purchase in the session for **Send early after quiet (minutes)**, or
* **Max wait (minutes)** has passed since the first purchase.

The rule is time-based only. ElasticFunnels does not get a "funnel finished" signal: reaching the thank-you page does not send the order early.

**Example** with Max wait 15 and Send early after quiet 5: a buyer orders at 10:00, takes an upsell at 10:02 and declines the downsell. The order is sent around 10:07 with both items. A buyer who keeps buying every few minutes is sent at 10:15 at the latest.

On a merged order, the customer and shipping details come from the main sale, and the totals, tax, shipping and discount are added up across all the lines. A purchase that comes in after the order was sent goes to Shopify as its own order.

### Gift orders

When a buyer sends bonus items as a gift, the gift is synced as its **own \$0 order** tagged `gift`, with the recipient's address. Its notes name the buyer's order and include the gift message. A gift is never merged into the buyer's order.

## What the Shopify order contains

<AccordionGroup>
  <Accordion title="Status and payment">
    * Financial status **paid** (payment was collected in ElasticFunnels)
    * A sale transaction for the order total, with the payment method as the gateway name. A \$0 gift order has no transaction
    * Shopify sends no order confirmation or receipt email to the customer
  </Accordion>

  <Accordion title="Customer and addresses">
    * Email, first and last name, phone
    * Billing and shipping address
    * If Shopify rejects the phone number, the order is sent again without it
  </Accordion>

  <Accordion title="Line items">
    * Product name, quantity and the price the customer paid
    * **SKU** from the product's SKU field in ElasticFunnels (the product code when the SKU is empty)
    * Variant name, when the product has one
    * Custom line items: not linked to Shopify products, so Shopify stock does not change
  </Accordion>

  <Accordion title="Totals">
    * Shipping line
    * Tax line with the tax exactly as charged in ElasticFunnels (Shopify does not recalculate it)
    * Discount
    * Processed date set to the purchase time
  </Accordion>

  <Accordion title="Tags, name and notes">
    * Tags `ElasticFunnels` and `ElasticFunnel` (the older tag is kept so existing Shopify Flow and 3PL rules keep matching), plus `gift` on gift orders
    * Source `ElasticFunnels`
    * Order name `#` followed by the ElasticFunnels order number
    * Order notes with the EF order ID, EF order number and funnel ID, plus provider, tracking and carrier when an ElasticFunnels fulfillment integration already has them
  </Accordion>
</AccordionGroup>

```
Order Source: ElasticFunnel
EF Order ID: ord_12345
EF Order Number: ABC123XYZ
Funnel ID: 42
```

## Refunds and cancellations

When you refund a synced purchase in ElasticFunnels:

* **Full refund:** the Shopify order is cancelled, which stops a 3PL app from shipping it. Shopify does not email the customer.
* **Partial refund:** a refund for that amount is created on the Shopify order. Items are not restocked and Shopify does not email the customer.
* **Full refund of one purchase on a merged order** (for example only the upsell): only that purchase's lines are refunded on the Shopify order, and the rest of the order still ships. The Shopify order is cancelled only once every purchase on it has been refunded.

ElasticFunnels only cancels or refunds orders it created. Orders you created yourself in Shopify, or that came from your Shopify store, are never touched. If ElasticFunnels cannot confirm that it created an order, it does nothing.

This works one way only: a cancellation or refund made in the Shopify admin is not carried back to ElasticFunnels.

## Tracking back from Shopify

When your store or the 3PL app connected to it fulfills a synced order in Shopify with a tracking number, ElasticFunnels picks it up:

* Every ElasticFunnels purchase on that Shopify order gets the **tracking number**, **carrier** and **tracking URL**, and is marked **shipped**.
* The buyer gets **one** shipped email per Shopify order, even when the order merges several purchases. It uses the shipped email set up on the merchant. No email is sent for a shipment older than 3 days (for example when an old order is edited in Shopify); its tracking is still recorded.
* If the order was paid through a [PayPal](/merchants/paypal) merchant, the tracking number is also sent to PayPal.
* Purchases already shipped by one of the ElasticFunnels fulfillment integrations (ShipOffers, Jetpack) keep the tracking from that integration.

There is nothing to turn on: ElasticFunnels registers the Shopify notifications it needs when order sync is on. Only the first fulfillment with a tracking number is used.

## Orders that are not synced

* Orders paid through the **Shop Pay** or **Shopify Checkout** merchants. They already exist in Shopify.
* Orders from merchants or affiliates excluded by your filters.
* Test orders, unless **Send test orders** is on.

## Products in Shopify

While **Sync orders to Shopify** is on, saving the integration or clicking **Sync products** creates each ElasticFunnels product in Shopify as a product with one variant: your ElasticFunnels title and price, the product code as SKU, vendor `ElasticFunnels`, and inventory not tracked. **Sync products** only creates products that are not in Shopify yet; it does not update ones already there. Later edits to a product are sent to Shopify only for stores connected with **Enable Shop Pay Merchant** turned on.

Synced orders do not use these products. They still arrive as custom line items, so creating products in Shopify does not make Shopify stock go down.

## Retries

If Shopify rejects the order or does not answer, the order is tried again up to 5 times: after 5, 15, 30, 60 and 120 minutes. A retry never creates a duplicate: if the order already exists in Shopify, ElasticFunnels uses it. After the last retry the sync is marked failed. Contact support and we can send the order again.

## Finding synced orders in Shopify

* **Tag filter:** Shopify Admin → **Orders** → **Filters** → **Tagged with** `ElasticFunnels`
* **Order name:** search for the ElasticFunnels order number
* **Order notes:** each order lists the EF order ID, order number and funnel ID

## Troubleshooting

<AccordionGroup>
  <Accordion title="Orders are not arriving in Shopify">
    1. Check that **Sync orders to Shopify** is on.
    2. Check the **Merchants** and **Affiliate Filtering** settings: the order's merchant or affiliate may be excluded.
    3. If it was a test order, **Send test orders** must be on.
    4. Orders paid through Shop Pay or Shopify Checkout are never synced; they are already in Shopify.
    5. With merging on, the order waits up to **Max wait (minutes)** before it is sent.
    6. Contact support if the order still does not appear.
  </Accordion>

  <Accordion title="&#x22;Shopify app not set up&#x22; when connecting">
    The custom Shopify app for your brand has not been created yet. Contact the ElasticFunnels team for an install link.
  </Accordion>

  <Accordion title="Shopify stock did not go down">
    Expected. Orders use custom line items that are not linked to your Shopify variants, so Shopify does not change its inventory. Track stock in ElasticFunnels or in your 3PL.
  </Accordion>

  <Accordion title="Prices differ from my Shopify catalog">
    Expected. The order carries the price the customer paid in ElasticFunnels, not your Shopify catalog price.
  </Accordion>

  <Accordion title="Tax in Shopify differs from ElasticFunnels">
    ElasticFunnels sends the tax exactly as collected. If Shopify shows a different number, Shopify's automatic tax is also on. See [Tax](/integrations/tax).
  </Accordion>

  <Accordion title="The upsell arrived as a separate order">
    Merging is off (**Max wait (minutes)** is 0), or the upsell was bought after the merged order had already been sent. Raise **Send early after quiet (minutes)** if your buyers take longer between offers.
  </Accordion>
</AccordionGroup>

## Data and privacy

The order and customer details stay in ElasticFunnels as part of your conversions and customer records; Shopify receives a copy to create the order. The Shopify app answers Shopify's required privacy webhooks:

* **customers/data\_request**: customer data export requests
* **customers/redact**: customer data deletion requests
* **shop/redact**: shop data deletion after the app is uninstalled

If you uninstall the app from Shopify, the integration is disabled and syncing stops. Orders already in Shopify stay there.

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Do I need my products in Shopify first?">
    No. Orders are created with custom line items, so they do not need matching Shopify products. If you want your products listed in Shopify anyway, use **Sync products**.
  </Accordion>

  <Accordion title="Does a synced order reduce my Shopify stock?">
    No. The lines are not linked to Shopify variants, so Shopify inventory does not change.
  </Accordion>

  <Accordion title="Can ElasticFunnels import my Shopify products?">
    No. Products are created in ElasticFunnels and can be pushed to Shopify, not the other way round.
  </Accordion>

  <Accordion title="Can I connect more than one Shopify store?">
    One store per brand. Use a separate brand for each store.
  </Accordion>

  <Accordion title="Does this sync refunds?">
    Yes, from ElasticFunnels to Shopify: a full refund cancels the Shopify order, a partial refund creates a Shopify refund. Refunds made in Shopify do not come back to ElasticFunnels.
  </Accordion>

  <Accordion title="Can the main sale and upsells arrive as one order?">
    Yes. Set **Max wait (minutes)** above 0. See [Merge the funnel into one order](#merge-the-funnel-into-one-order).
  </Accordion>

  <Accordion title="Will test orders end up in my store?">
    Only if you turn on **Send test orders**. It is off by default.
  </Accordion>

  <Accordion title="What if Shopify is down?">
    The order is retried up to 5 times over about four hours, without creating duplicates.
  </Accordion>

  <Accordion title="Can I sync orders from before I connected the store?">
    Contact support. We can send past orders for you.
  </Accordion>

  <Accordion title="What if my 3PL is connected to Shopify?">
    Your 3PL sees the synced orders in Shopify and fulfills them as usual. When it adds the tracking number in Shopify, the tracking comes back to ElasticFunnels and the buyer gets a shipped email. See [Tracking back from Shopify](#tracking-back-from-shopify).
  </Accordion>

  <Accordion title="I refunded only the upsell. Does the whole Shopify order get cancelled?">
    No. On a merged order, a full refund of one purchase refunds only its lines. The order is cancelled only once every purchase on it is refunded.
  </Accordion>
</AccordionGroup>

## Using Shopify as checkout

To **sell through Shopify** from your funnels instead of syncing orders from other gateways, use one of these merchants:

* **[Shopify Checkout](/merchants/shopify-checkout)**: sends visitors to your Shopify cart and native checkout.
* **[Shop Pay](/merchants/shop-pay)**: creates a draft order in Shopify and sends the customer to Shopify checkout, with Shop Pay for returning customers; supports bumps.

Both need your Shopify store connected (**Integrations** → **Operations** → **Shopify**). Neither supports one-click upsells, because the payment happens on Shopify. Orders paid through them are already in Shopify, so order sync skips them.

## Next Steps

<CardGroup>
  <Card title="Fulfillment" icon="truck" href="/integrations/fulfillment">
    Send orders to ShipOffers or Jetpack directly from ElasticFunnels
  </Card>

  <Card title="Tax" icon="calculator" href="/integrations/tax">
    Calculate tax at checkout so Shopify receives the right amounts
  </Card>

  <Card title="Shop Pay" icon="bag-shopping" href="/merchants/shop-pay">
    Use Shopify draft orders and Shop Pay as your checkout
  </Card>

  <Card title="Shopify Checkout" icon="cart-shopping" href="/merchants/shopify-checkout">
    Send funnel visitors to your Shopify cart
  </Card>
</CardGroup>


# Taboola Integration
Source: https://docs.elasticfunnels.io/integrations/taboola

Send conversion postbacks to Taboola for native advertising campaign optimization

## Overview

The Taboola integration enables S2S (server-to-server) conversion tracking to Taboola's native advertising platform. When conversions occur in ElasticFunnels, postbacks are automatically sent to Taboola with conversion data, enabling accurate campaign attribution and optimization.

## What This Integration Provides

<CardGroup>
  <Card title="Conversion Postbacks" icon="arrow-trend-up">
    Automatically send conversion data to Taboola when purchases occur
  </Card>

  <Card title="Campaign Optimization" icon="chart-line">
    Help Taboola optimize your campaigns based on actual conversions
  </Card>

  <Card title="Multiple Accounts" icon="layer-group">
    Support for multiple Taboola accounts with different settings
  </Card>

  <Card title="Flexible Parameters" icon="sliders">
    Configurable parameter builder with all Taboola-supported variables
  </Card>
</CardGroup>

## How It Works

### The Flow

1. **User clicks Taboola ad** → Taboola generates click ID
2. **Taboola redirects to your page** → Appends click ID to URL (e.g., `?click_id=ABC123`)
3. **ElasticFunnels captures click ID** → Stored in click tracking data
4. **Customer makes purchase** → Via any payment gateway
5. **Postback automatically sent** → Conversion data sent to Taboola with click ID for attribution

### What Makes This Unique

Taboola postbacks help optimize your native advertising campaigns by sending conversion data back to Taboola, similar to how conversion pixels work for Facebook or Google Ads.

<Info>
  This integration is perfect for native advertising campaigns where you want Taboola's algorithm to optimize based on actual conversions, not just clicks.
</Info>

## Setup Guide

### Step 1: Get Your Account ID

1. Log into your Taboola account
2. Navigate to **Account Settings**
3. Find your **Account ID** (format: `networkname-advertiser`)
4. Copy this ID - you'll need it in the next step

<Info>
  The Account ID identifies your Taboola advertiser account. It's typically in the format `networkname-advertiser`.
</Info>

### Step 2: Configure Event in Taboola Realize

Before setting up the integration, configure your conversion event in Taboola:

1. Go to **Taboola Realize** (Taboola's tracking platform)
2. Navigate to **Conversion Settings**
3. Create or note your **Event Name** (e.g., `purchase`)
4. This must match **exactly** (case-sensitive)

<Warning>
  The Event Name must match exactly what you configure in ElasticFunnels, or conversions won't be tracked. It's case-sensitive!
</Warning>

### Step 3: Create Taboola Integration

1. Navigate to **Settings → Integrations → Advertising**
2. Find **Taboola** and click **"Activate"**
3. Enter your **Account ID**
4. Enter your **Event Name** (must match Taboola Realize)
5. The postback URL will be automatically generated

### Step 4: Configure Click ID Parameter

Select which parameter Taboola uses to pass the click ID to your pages:

<AccordionGroup>
  <Accordion title="click_id or click-id (Most Common)">
    Taboola passes the click ID as `click_id` or `click-id` in the URL.

    **Example:** `yoursite.com/page?click_id=ABC123`

    **Use when:** Your Taboola campaign uses standard tracking parameters.
  </Accordion>

  <Accordion title="taboola_click_id (Alternative)">
    Some Taboola campaigns use a prefixed parameter name.

    **Example:** `yoursite.com/page?taboola_click_id=ABC123`

    **Use when:** Your Taboola tracking links use this parameter name.
  </Accordion>
</AccordionGroup>

<Info>
  **How to check:** Look at a sample Taboola tracking link. The parameter that contains the long unique ID is your click ID parameter.
</Info>

### Step 5: Customize Parameters (Optional)

Use the parameter builder to customize what data is sent to Taboola:

1. **Default parameters** are pre-configured (click-id, name, revenue, currency, orderid)
2. **Add custom parameters** by clicking "+ Add Parameter"
3. **Select variables** from the dropdown for each parameter
4. **Remove optional parameters** by clicking the X button

**Available Variables:**

* **Required:** click\_id, event\_name
* **Conversion:** order\_id, revenue, currency, quantity
* **Customer:** email, phone

<Warning>
  **click-id and name are required** and cannot be removed. Taboola needs these to attribute conversions correctly.
</Warning>

### Step 6: Configure Merchant Filtering (Optional)

Choose which merchants should send postbacks to Taboola:

**All Merchants (Default):**

* Postbacks sent for conversions from any payment gateway

**Specific Merchants:**

* Click "Specific merchants" radio button
* Select which merchants to track
* Only selected merchants will send postbacks

### Step 7: Configure Affiliate Filtering (Optional)

Control which affiliates' conversions are sent to Taboola:

**All Affiliates (Default):**

* Postbacks sent for all affiliate conversions

**Whitelist (Only These):**

* Click "+ Add Affiliate ID" to add allowed affiliate IDs
* Only conversions from these affiliate IDs will send postbacks
* Useful for tracking only your top-performing affiliates

**Blacklist (Exclude These):**

* Click "+ Add Affiliate ID" to add blocked affiliate IDs
* Conversions from these affiliate IDs will NOT send postbacks
* Useful for excluding fraudulent or low-quality affiliates

<Tip>
  Affiliate IDs come from your payment gateway (BuyGoods, ClickBank, etc.). They identify which affiliate generated the sale.
</Tip>

### Step 8: Save and Test

1. Click **"Save Integration"**
2. Test by clicking a Taboola ad and making a purchase
3. Verify conversion appears in Taboola dashboard

## Configuration Options

### Postback URL

The postback URL is automatically generated from your Account ID and parameters:

**Format:**

```
https://trc.taboola.com/actions-handler/log/{ACCOUNT_ID}/s2s-action?click-id={click_id}&name={event_name}&revenue={revenue}&currency={currency}&orderid={order_id}
```

**When a conversion happens, macros are replaced:**

```
https://trc.taboola.com/actions-handler/log/mynetwork-advertiser/s2s-action?click-id=ABC123&name=purchase&revenue=99.99&currency=USD&orderid=ORD456
```

### Account ID

Your Taboola advertiser account identifier. Typically in format `networkname-advertiser`.

### Event Name

The event name **must match** what's configured in Taboola Realize. Common values:

* `purchase` - For completed purchases
* `lead` - For lead submissions
* `signup` - For registrations
* Custom names as configured in your Taboola account

<Warning>
  Event Name is **case-sensitive**. `purchase` ≠ `Purchase` ≠ `PURCHASE`
</Warning>

### Click ID Parameter

Tells ElasticFunnels which URL parameter contains Taboola's click ID. Options:

* `click_id` (common)
* `click-id` (Taboola standard)
* `taboola_click_id` (alternative)

## Parameter Builder

### How to Use

<Steps>
  <Step title="Add Parameter">
    Click "+ Add Parameter" to add a new field
  </Step>

  <Step title="Enter Parameter Name">
    Type the parameter name (must match Taboola's requirements)
  </Step>

  <Step title="Select Variable">
    Choose from the dropdown which data to send
  </Step>

  <Step title="View Generated URL">
    The URL field updates automatically
  </Step>
</Steps>

### Two-Way Sync

The URL and parameter builder stay in sync:

* **Edit URL directly** → Parameters automatically parse and display
* **Change parameters** → URL automatically updates
* **Change Account ID or Event Name** → URL updates to match

## Available Variables

### Required Variables

<ParamField type="string">
  Taboola click ID captured from the tracking URL. **Required for attribution.** Must be exactly `click-id` (with hyphen).
</ParamField>

<ParamField type="string">
  Event name as configured in Taboola Realize. **Case-sensitive.** Must match exactly.
</ParamField>

### Conversion Data

<ParamField type="number">
  Conversion amount (formatted as decimal, e.g., 99.99)
</ParamField>

<ParamField type="string">
  Currency code (e.g., USD, GBP, EUR). Supports 19 currencies.
</ParamField>

<ParamField type="string">
  Your order/conversion ID from ElasticFunnels
</ParamField>

<ParamField type="integer">
  Item quantity in the order
</ParamField>

### Customer Information

<ParamField type="string">
  Customer email address (optional)
</ParamField>

<ParamField type="string">
  Customer phone number (optional)
</ParamField>

## Supported Currencies

Taboola supports the following currencies:

`AUD`, `BRL`, `CAD`, `CNY`, `EUR`, `GBP`, `HKD`, `ILS`, `INR`, `JPY`, `KRW`, `MXN`, `NZD`, `RUB`, `SGD`, `THB`, `TRY`, `USD`, `ZAR`

<Info>
  If currency is omitted, Taboola uses your account's default currency.
</Info>

## Use Cases

### For Advertisers

Track your native advertising performance:

* Optimize campaigns based on conversions
* Track ROI and ROAS accurately
* Multiple campaign tracking with different account IDs
* Event-based conversion tracking

### For Agencies

Manage multiple client accounts:

* Separate integration per client
* Different event names per campaign type
* Merchant-specific tracking
* Campaign performance isolation

## Troubleshooting

<AccordionGroup>
  <Accordion title="No Conversions Showing in Taboola">
    **Possible Causes:**

    * Click ID not found in click data
    * Event Name doesn't match Taboola Realize
    * Integration not enabled

    **Solution:**

    1. Verify customer clicked a Taboola ad before purchasing
    2. Check Event Name matches Taboola Realize exactly (case-sensitive)
    3. Verify integration is enabled
    4. Check ElasticFunnels logs for postback attempts
  </Accordion>

  <Accordion title="Event Name Not Matching">
    **Issue:** Taboola reports "Event not found" or similar error

    **Solution:**

    1. Log into Taboola Realize
    2. Check the exact Event Name (case-sensitive)
    3. Update ElasticFunnels integration to match exactly
    4. Event Name must be configured in Taboola first
  </Accordion>

  <Accordion title="Click ID Not Found">
    **Issue:** Postbacks not sending because click ID isn't detected

    **Solution:**

    1. Check which parameter Taboola uses in tracking URLs
    2. Update "Click ID Parameter" dropdown to match
    3. Common options: click\_id, click-id, taboola\_click\_id
    4. System automatically checks fallbacks
  </Accordion>

  <Accordion title="204 No Content Response">
    **Explanation:** This is normal! Taboola returns HTTP 204 (No Content) for successful postbacks.

    **What it means:** Your postback was received and processed successfully by Taboola.
  </Accordion>
</AccordionGroup>

## Best Practices

<Steps>
  <Step title="Configure Event in Taboola First">
    Always set up your conversion event in Taboola Realize before configuring ElasticFunnels.
  </Step>

  <Step title="Match Event Name Exactly">
    Event Name is case-sensitive. `purchase` ≠ `Purchase`. Double-check spelling and capitalization.
  </Step>

  <Step title="Test with Small Campaign">
    Test the integration with a small Taboola campaign first to verify tracking works.
  </Step>

  <Step title="Monitor Taboola Dashboard">
    Check your Taboola dashboard to confirm conversions are being received.
  </Step>

  <Step title="Use Standard Parameter Names">
    Stick to Taboola's standard parameter names (click-id, revenue, orderid) for compatibility.
  </Step>
</Steps>

## Technical Details

### Postback Method

Postbacks are sent via **HTTP GET requests**, which is the standard for Taboola S2S integration.

### Response Codes

* **204 No Content** - Success (standard Taboola response)
* **200 OK** - Also considered success
* **4xx/5xx** - Error (logged for debugging)

### Error Handling

The integration reports common errors clearly:

* Failed postbacks are logged but don't break conversion creation
* Network timeouts handled gracefully
* Invalid URLs caught and logged
* System continues working even if Taboola is temporarily unavailable

### Queue Processing

Postbacks are processed asynchronously via the `conversions` queue:

* Doesn't slow down conversion creation
* Automatic retry on temporary failures
* Can be monitored via queue logs

## Compatibility

### Works With Any Payment Gateway

The Taboola integration works regardless of which payment gateway you use. Taboola tracks attribution (which ad generated the conversion), independent of how payment is processed.

### Works With Multiple Campaigns

Compatible with running multiple Taboola campaigns:

* Different Account IDs per campaign
* Different Event Names per conversion type
* Merchant-specific tracking per campaign

## Integration Architecture

<Note>
  **Important:** Taboola is an **outbound integration** - we send conversion data TO Taboola, we don't receive data FROM Taboola. This is the same pattern as Google Ads and Meta Ads conversion tracking.
</Note>

### What This Means

* **No incoming postbacks** - Taboola doesn't send data to us
* **Triggered by conversions** - Postbacks fire when purchases occur
* **Attribution only** - Used to tell Taboola which ads generated conversions
* **Works with any merchant** - Compatible with any payment processor

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Which click ID parameter should I use?">
    **Answer:** Look at a sample Taboola tracking link. The parameter containing the unique ID is your click ID parameter.

    * Most campaigns use `click_id` or `click-id`
    * Some use `taboola_click_id`
    * The system automatically checks fallbacks
  </Accordion>

  <Accordion title="What's the difference between Event Name and Conversion Name?">
    **Answer:**

    * **Event Name** - Technical identifier used in postbacks (e.g., `purchase`)
    * **Conversion Name** - Display name in Taboola dashboard (e.g., "Product Purchase")

    Use the Event Name from Taboola Realize, not the Conversion Name.
  </Accordion>

  <Accordion title="Can I track multiple conversion types?">
    **Answer:** Yes! Create separate integrations for each conversion type:

    * Integration 1: Event Name = `purchase` (completed purchases)
    * Integration 2: Event Name = `lead` (lead submissions)
    * Integration 3: Event Name = `signup` (registrations)

    Each integration can have different merchant filtering and settings.
  </Accordion>

  <Accordion title="Why does Taboola return 204 No Content?">
    **Answer:** This is normal and expected. HTTP 204 means "success with no response body." It's Taboola's standard way of acknowledging receipt of your postback.
  </Accordion>

  <Accordion title="How long until conversions appear in Taboola?">
    **Answer:** Postbacks are sent immediately when conversions are created (within seconds). Taboola should show the conversion in real-time or within a few minutes.
  </Accordion>

  <Accordion title="Can I test before going live?">
    **Answer:** Yes!

    1. Set up the integration
    2. Click a Taboola test ad
    3. Make a small test purchase
    4. Check Taboola dashboard to verify conversion was received
    5. Review ElasticFunnels Logs → External Postbacks to confirm sending
  </Accordion>

  <Accordion title="What's the difference between Whitelist and Blacklist for affiliates?">
    **Answer:**

    * **Whitelist** - Only send postbacks for specific affiliate IDs (e.g., only your top performers)
    * **Blacklist** - Block specific affiliate IDs from sending postbacks (e.g., exclude fraud)
    * **All affiliates** - Send postbacks for everyone (default)

    Affiliate IDs come from your payment gateway and identify which affiliate generated the sale.
  </Accordion>

  <Accordion title="Can I filter by both Merchants and Affiliates?">
    **Answer:** Yes! Filters can be combined:

    * Merchant filter: Only specific payment gateways
    * Affiliate whitelist: Only specific affiliate IDs
    * Result: Highly targeted tracking
  </Accordion>
</AccordionGroup>

## URL Parameter Format

### Standard Taboola Format

Taboola requires the `click-id` parameter to use a **hyphen** (not underscore):

```
✅ Correct: ?click-id=ABC123
❌ Wrong:   ?click_id=ABC123  (underscore)
```

<Warning>
  The parameter name must be exactly `click-id` in the URL sent to Taboola, or conversions won't be recorded.
</Warning>

### How We Handle This

Our integration automatically:

* Uses `click-id` (with hyphen) in the postback URL to Taboola
* But can detect `click_id`, `click-id`, or `taboola_click_id` from incoming URLs
* You don't need to worry about the hyphen/underscore difference

## Multiple Integrations

You can create multiple Taboola integrations for different use cases:

### When to Create Multiple Integrations

* **Different campaigns** - Separate account IDs
* **Different conversion types** - Different event names (purchase, lead, signup)
* **Different merchants** - Track specific payment gateways
* **Client separation** - Agencies managing multiple clients

### How It Works

Each integration is independent:

* Has its own Account ID
* Has its own Event Name
* Has its own merchant filtering
* Sends separately to Taboola

<Tip>
  Name each integration clearly (e.g., "Taboola - Purchase Events", "Taboola - Lead Events") to keep them organized.
</Tip>

## Logging & Monitoring

### View Postback Logs

1. Navigate to **Logs → External Postbacks**
2. Filter to see Taboola postbacks
3. View success/failure status
4. See request/response details
5. Debug any issues

### What Gets Logged

* Postback URL sent
* All parameters and values
* Response code (204 = success)
* Response body
* Timing information

## Security & Privacy

### Data Handling

* **Click ID** - Unique identifier from Taboola (not sensitive)
* **Customer Data** - Only sent if configured (email, phone are optional)
* **HTTPS Only** - All postbacks use secure connections
* **URL Encoding** - All data properly encoded

### Privacy Considerations

You can exclude customer information:

* Disable email parameter if needed
* Disable phone parameter
* Still track conversions with just revenue and order ID

## External Resources

<CardGroup>
  <Card title="Taboola S2S Integration Docs" icon="book" href="https://developers.taboola.com/pixel/docs/s2s-manual-integration">
    Official Taboola server-to-server integration guide
  </Card>

  <Card title="Taboola Postback URL Reference" icon="link" href="https://developers.taboola.com/pixel/docs/the-postback-url">
    Complete postback URL parameter reference
  </Card>

  <Card title="Taboola Realize" icon="chart-line" href="https://ads.realizeperformance.com/tracking">
    Configure conversion events and tracking
  </Card>

  <Card title="Taboola Help Center" icon="question-circle" href="https://help.taboola.com/hc/en-us">
    Taboola's support documentation
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Google Ads Integration" icon="rectangle-ad" href="/integrations/google-ads">
    Set up Google Ads for additional conversion tracking
  </Card>

  <Card title="Meta Ads Integration" icon="rectangle-ad" href="/integrations/meta-ads">
    Connect Meta Ads for Facebook conversion tracking
  </Card>

  <Card title="Analytics Dashboard" icon="chart-mixed" href="/analytics/overview">
    View your conversion and performance data
  </Card>

  <Card title="External Postbacks Log" icon="list" href="/logs">
    Monitor your Taboola postback attempts
  </Card>
</CardGroup>


# Sales Tax Integrations
Source: https://docs.elasticfunnels.io/integrations/tax

Calculate sales tax at checkout in real time using TaxJar, Avalara, or TaxCloud.

## Overview

ElasticFunnels can calculate sales tax at checkout using any of three external services. The active integration is queried for every cart that has a shipping or billing state subject to sales tax, and the calculated rate is applied to the order before payment.

You can configure **multiple** tax integrations per brand. The offer app tries them in the order shown on the integrations list — useful for fallback (e.g. TaxJar primary, Avalara backup).

## Supported providers

| Provider | Best for | Auth |
| - | - | - |
| **TaxJar** | US sales tax across all 50 states; SaaS-friendly | API key |
| **Avalara** | Enterprise; global jurisdictions, exemption handling, certificates | Account ID + License key |
| **TaxCloud** | Free tier for SST member states (member sellers pay nothing) | API Login ID + API Key |

## How it works

1. Customer fills in their billing/shipping address on the checkout step.
2. Before tax is shown, EF asks the configured tax provider for the rate using:
   * The customer's destination state, ZIP, and city
   * The order line items and total
3. The provider returns the tax amount.
4. EF adds the tax line to the order total and re-renders the order summary.
5. When payment succeeds, the tax amount stored on the conversion is exactly what was returned by the provider.

The same calculated tax flows into Shopify Order Sync (so your accountant sees matching numbers in Shopify), into the EF reports, and into the receipt email.

## Setup

### TaxJar

<Steps>
  <Step title="Get an API token">
    Sign up at [taxjar.com](https://www.taxjar.com). Open **Account** → **TaxJar API** → **API Tokens** and copy your token.
  </Step>

  <Step title="Activate in EF">
    Go to **Integrations** → **Tax** → **TaxJar**. Paste the token, save.
  </Step>

  <Step title="(Optional) Set nexus states">
    TaxJar uses your nexus configuration on its dashboard to decide which orders are taxable. Make sure your nexus list in TaxJar matches the states where you collect tax.
  </Step>
</Steps>

### Avalara

<Steps>
  <Step title="Get account credentials">
    From your Avalara account: **Settings** → **License and API Keys** → copy the **Account ID** and **License Key**.
  </Step>

  <Step title="Activate in EF">
    Go to **Integrations** → **Tax** → **Avalara**. Paste both credentials and save. Toggle **Sandbox** during setup if you want to use the sandbox environment.
  </Step>

  <Step title="Configure company code">
    Set the **Company Code** that matches the company entity in your Avalara dashboard. Avalara needs this to apply the right tax profile.
  </Step>
</Steps>

### TaxCloud

<Steps>
  <Step title="Sign up">
    Sign up at [taxcloud.com](https://taxcloud.com). The plan is free for sellers in SST member states.
  </Step>

  <Step title="Get API credentials">
    Open **Websites** → pick your site → **Manage Tax States** to confirm coverage, then copy the **API Login ID** and **API Key**.
  </Step>

  <Step title="Activate in EF">
    Go to **Integrations** → **Tax** → **TaxCloud**. Paste both values, save.
  </Step>
</Steps>

## Multiple integrations & fallbacks

If you create more than one tax integration, EF tries them in order until one returns a valid response:

1. First active integration is queried.
2. If it returns an error or is unavailable, the next is tried.
3. If all integrations fail, the order falls back to **no tax** (and a warning is logged).

This is useful for high-availability setups (TaxJar + Avalara as backup) or for switching providers without downtime.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tax shows as $0 on checkout">
    Either the destination address isn't taxable in your nexus configuration, the integration credentials are wrong, or the integration call timed out. Check the checkout's developer log on the conversion record.
  </Accordion>

  <Accordion title="Tax shown in EF doesn't match Shopify after sync">
    Shopify Order Sync sends the tax amount **exactly as collected** in EF. If Shopify shows a different number, you have Shopify's automatic tax also turned on — turn it off for orders tagged `ElasticFunnel`, or set Shopify to "tax included" so it doesn't recompute.
  </Accordion>

  <Accordion title="Avalara returns 'TaxCalculationFailed'">
    The most common cause is a missing `companyCode`. Check the integration form has the correct company code from your Avalara dashboard.
  </Accordion>
</AccordionGroup>


# TrackPlay Video Player
Source: https://docs.elasticfunnels.io/integrations/trackplay

Sync videos from TrackPlay and embed their tracking-aware player on your funnel pages.

## Overview

[TrackPlay](https://trackplay.io) is a video player built for direct-response funnels — heatmaps, watch-rate buckets, "video pixel" event tracking, and conversion-aware controls (pitch reveal, CTA show / hide, autoplay rules).

The ElasticFunnels integration connects to your TrackPlay workspace so the EF page builder can list your videos and insert the right embed code without copy-pasting from TrackPlay.

## What you get

* **Video picker in the page builder** — Inserting a TrackPlay video shows a searchable list of every video in your workspace, with thumbnails.
* **Always-current embed** — When you change the player or settings on TrackPlay, the embed on your EF page picks the new settings up automatically (no need to re-export the embed code).
* **Per-video event hooks** — TrackPlay's `onPlay`, `onProgress`, and `onComplete` events are exposed to EF page interactions, so you can fire show/hide rules, scroll-to-CTA, or analytics events from the player's lifecycle.

## Setup

<Steps>
  <Step title="Get your TrackPlay API key">
    Log into [app.trackplay.io](https://app.trackplay.io). Go to **Workspace Settings** → **API Key**. Generate or copy the key (format `tp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`).
  </Step>

  <Step title="Activate the integration in EF">
    Go to **Integrations** → **Utilities** → **TrackPlay**. Paste the API key and save.
  </Step>

  <Step title="Insert a video on a page">
    In the page builder, add a **Video** block. The TrackPlay tab shows the list of videos in your workspace — pick one and save the page.
  </Step>

  <Step title="(Optional) Wire interactions">
    Open the page's **Interactions** panel and bind on-event rules to the TrackPlay video (e.g. "show pitch button at 25%", "scroll to CTA at 90%").
  </Step>
</Steps>

## Notes

* **Player chrome and behavior is configured in TrackPlay.** EF doesn't override the player; whatever is set in the TrackPlay dashboard renders on the EF page.
* **Domain whitelisting.** If TrackPlay's player is configured to only embed on whitelisted domains, add your EF domain to that list inside TrackPlay.
* **Analytics.** TrackPlay's analytics live inside TrackPlay. For funnel-level conversion tracking, EF still records the conversion regardless of whether the user finished the video.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Video list is empty in EF">
    The API key was rejected. Re-copy from TrackPlay's Workspace Settings and paste again — keys are 32 chars after the `tp_` prefix.
  </Accordion>

  <Accordion title="Video doesn't play on the live page">
    The most common cause is a domain restriction in TrackPlay. Open the player settings on TrackPlay and add the EF page's domain (or `*.elasticfunnels.io` for testing) to the allowed embed domains.
  </Accordion>

  <Accordion title="Interactions don't fire">
    Confirm you bound the interaction to the TrackPlay video block (not a generic video element) so EF subscribes to the TrackPlay JS events instead of the native HTML5 video events.
  </Accordion>
</AccordionGroup>


# Twilio Integration
Source: https://docs.elasticfunnels.io/integrations/twilio

Send SMS, run voice flows, and verify phone numbers from automations using your Twilio account.

## Overview

The Twilio integration lets your ElasticFunnels automations send SMS / MMS messages, place outbound voice calls with TwiML instructions, start phone-verification flows, and check verification codes. The same Twilio account you connect here also powers the **call center** module's outbound dialing.

## What you get

| Action | What it does |
| - | - |
| Send SMS / MMS | Sends a message from one of your purchased Twilio numbers |
| Make voice call | Dials an outbound number and plays / interacts via a TwiML URL |
| Start verification | Sends a one-time SMS / call code through Twilio Verify |
| Check verification code | Validates the code the user submitted |
| Get message status | Reads delivery status of a previously sent message |
| Get call status | Reads the disposition of a previously placed call |

The form dynamically lists the phone numbers and Verify services on your Twilio account so you can pick them by friendly name instead of pasting IDs.

## Setup

<Steps>
  <Step title="Create an API key in Twilio">
    Log into the [Twilio Console](https://console.twilio.com). Open **Settings** → **API keys & tokens** → **Create API key** (Standard type). Copy the **Key SID** and **Secret** immediately — the secret is only shown once.
  </Step>

  <Step title="Copy your Account SID">
    From the Twilio Console homepage, copy the **Account SID**.
  </Step>

  <Step title="Activate the integration in EF">
    Go to **Integrations** → **Communications** → **Twilio**. Paste **Account SID**, **API Key**, and **API Secret**. Save.
  </Step>

  <Step title="(Voice) Buy a phone number">
    In Twilio: **Phone Numbers** → **Manage** → **Buy a number**. Numbers purchased here automatically appear in EF's number picker.
  </Step>

  <Step title="(Verification) Create a Verify service">
    In Twilio: **Verify** → **Services** → **Create Service**. Set the friendly name and channels (SMS, voice, email). The service shows up in EF's automation actions for `Start Verification` / `Check Verification`.
  </Step>

  <Step title="Use it in automations">
    Open **Automations**, drop a `Twilio: Send SMS` (or any other Twilio action) into a flow, and pick the from-number, message body, and optional media URL. Map ElasticFunnels variables like `{{customer.phone}}` into the to-number field.
  </Step>
</Steps>

## Common patterns

### Order receipt SMS

Trigger: `Conversion: purchase` → Action: `Twilio: Send SMS` to the customer phone with order number and tracking link.

### Two-factor login

Trigger: `Form: submitted` (login form) → Action: `Twilio: Start Verification` → Wait for user input on the next page → Action: `Twilio: Check Verification Code`.

### Abandoned cart SMS

Trigger: `Cart abandoned (2h)` → Condition: `customer.phone is not empty` → Action: `Twilio: Send SMS` with a recovery link.

### Outbound voice (call center)

The Organization Callcenter integration uses your Twilio credentials to place outbound calls from agent dashboards. No additional setup beyond connecting Twilio is required.

## Costs

You pay Twilio directly for messages, calls, and verifications based on their per-segment / per-minute pricing. ElasticFunnels does not mark up Twilio usage.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Messages not delivering to US numbers">
    US carriers require **A2P 10DLC registration** for application-to-person traffic. Register your brand and campaign inside the Twilio Console (**Messaging** → **Regulatory Compliance** → **A2P 10DLC**) before sending production traffic.
  </Accordion>

  <Accordion title="Verification codes never arrive">
    Check the Verify service has the right channels enabled, the destination country isn't blocked in your Twilio geo permissions, and your account isn't in trial mode (trial accounts can only message verified numbers).
  </Accordion>

  <Accordion title="Voice call disconnects immediately">
    The TwiML URL returned an error or invalid TwiML. Open **Twilio Console** → **Monitor** → **Logs** → **Errors** to see the call's failure detail.
  </Accordion>
</AccordionGroup>


# Customer Care Portal
Source: https://docs.elasticfunnels.io/members-area/customer-care

Let customers manage their subscriptions and request refunds directly from the members area.

The Customer Care portal adds two self-service features to the members area:

* **Manage** — Customers can pause, skip, or cancel a subscription (with optional retention offers). The manage page also shows a list of orders eligible for a refund.
* **Self-refund** — Customers can submit a refund request for eligible orders (one-time purchases or subscription first charges).

Both features are configured per merchant in **Merchant settings → Customer care** and are completely optional.

***

## Brand-level settings

Before configuring individual merchants, set the brand-wide customer support details in **Brand Settings → General** under the **Customer support** section:

| Setting | Purpose |
| - | - |
| **Support email** | Displayed to customers in error messages (e.g. "Please contact us at [support@yourbrand.com](mailto:support@yourbrand.com)"). |
| **Support phone** | Optional phone number displayed alongside the support email. |
| **Money-back guarantee (days)** | A brand-wide refund window. Orders older than this many days are automatically ineligible for a refund, regardless of per-merchant rules. Set to 0 or leave blank to disable. |

These values are stored as brand variables and are accessible in templates as `{{ brand.support_email }}`, `{{ brand.support_phone }}`, and `{{ brand.mbg_days }}`.

<Tip>
  When a refund request is denied, the error message automatically includes your support email and phone so customers know how to reach you. Make sure to fill these in.
</Tip>

***

## Enabling Customer Care

1. Navigate to **Merchants** and open a merchant configured with Stripe or NMI.
2. Click the **Customer care** tab.
3. Enable the features you want:
   * **Subscription management** — turns on the Manage page for active subscriptions.
   * **Self-refund** — allows customers to request a refund on eligible orders.
4. Save the merchant.

### Subscription management

When enabled, an active subscription card on `/members/subscription` will show a **Manage** button. Clicking it opens `/members/manage?tx=<transactionId>`.

<Note>
  Configure the exit survey reasons and retention offers in the **Retention offers** tab. The Customer care tab controls the feature toggle; the Retention offers tab controls which offers are shown.
</Note>

### Self-refund — eligibility rules

Eligibility is checked at two levels:

**Brand level** (checked first):

| Rule | What it checks |
| - | - |
| **Money-back guarantee (days)** | If set and the order is older than this window, it's automatically ineligible. |

**Merchant level** (checked second):

| Rule | What it checks |
| - | - |
| **Max days since purchase** | The order must have been placed within N days. |
| **Require not fulfilled** | Orders that have already been shipped, fulfilled, or delivered are excluded. |
| **Max order amount** | Orders above this dollar threshold are excluded. |

If an order passes both levels, a **Request refund** link appears on its card in `/members/orders` and in the refund candidates section on `/members/manage`.

### Self-refund — on-request action

When a customer submits a refund request, one of three things happens (your choice):

| Action | What happens |
| - | - |
| **Process refund automatically** | The refund is applied immediately via the payment gateway. The customer sees a confirmation that the refund will appear in 3–5 business days. |
| **Send email notification** | An email is sent to the configured **Notification email** address with order and customer details. The customer sees a "request received" message. |
| **Create support ticket** | A support ticket is created on behalf of the customer. The customer receives the ticket number. This option is only available when the brand has the Tickets module enabled. |

### Error messages

All customer-facing error messages are friendly and non-technical. When a refund is denied, the message includes your brand's support contact information automatically:

> "The refund window for this order has closed. Please contact us at [support@yourbrand.com](mailto:support@yourbrand.com) or call +1 800 555 0100."

If no support email or phone is configured, it falls back to:

> "Please contact our support team."

***

## The Manage page (`/members/manage`)

The manage page is a multi-step flow. Customers land here from the **Manage** button on their subscription card.

**Step 1 — Subscription summary + refund candidates**\
Shows the product name, current status, and next charge date with a "I want to cancel" action. Below the subscription card, any orders eligible for a refund are displayed with a "Request refund" link.

**Step 2 — Exit survey**\
Displays the exit survey reasons configured in the Retention offers tab. The customer selects the reason that applies.

**Step 3 — Retention offer** *(optional)*\
If a retention offer is configured for the selected reason, the customer is shown the offer (discount, pause, or downgrade). They can accept it or proceed to cancel.

**Step 4 — Outcome**\
Shows the result: cancelled, offer accepted, or an error.

### Refund candidates on the manage page

The manage page automatically shows refund-eligible orders below the subscription card. An order appears in this list when:

* `refund_eligible` is `true` (merchant rules pass)
* The order is not fully refunded
* The order is within the brand's money-back guarantee window (if configured)

Each candidate card displays the order number, date, how many days ago the order was placed, the total amount, and a link to the refund page.

### Customising the manage page

The built-in `members/manage` page is a starting point. You can build a fully custom version using the `getManageData()` backend function, `getOrders()`, and the `window.ef.customerCare` JavaScript API.

```liquid theme={null}
<script scope="backend">
  var data = getManageData(query.tx);
  if (!data) { redirect('/members/subscription'); }
  setVariable('manage', data);

  // Refund candidates
  var orders = getOrders('newest', 50);
  var mbgDays = brand.mbg_days || 0;
  var refundOrders = orders.filter(function(o) {
    if (!o.refund_eligible || o.refund.fully_refunded) return false;
    if (mbgDays > 0 && o.days_since_order != null && o.days_since_order >= mbgDays) return false;
    return true;
  });
  setVariable('refund_orders', refundOrders);
</script>
```

The `getManageData()` function returns `null` if the subscription doesn't exist, doesn't belong to the current customer, or manage is not enabled on the merchant. Use this to redirect before rendering the page.

***

## The Refund page (`/members/refund`)

The refund page lets a customer submit a refund request for a specific order. They arrive here from the **Request refund** link on an order card or from the manage page.

**What the customer sees:**

* A summary of the order (order number, date, amount).
* The refund amount (the full remaining balance — read-only).
* A text area for a reason.
* A submit button.

**Outcome states after submitting:**

| Outcome | Message shown |
| - | - |
| Auto refunded | "Your refund has been processed and will appear within 3–5 business days." |
| Queued for review | "Your refund request has been received. Our team will review it shortly." |
| Ticket created | "A support ticket has been created (#XXXXXXXX). We'll be in touch soon." |

### Customising the refund page

Build a custom page using `getRefundEligibility()` and `window.ef.customerCare.requestRefund()`:

```liquid theme={null}
<script scope="backend">
  var elig = getRefundEligibility(query.order);
  if (!elig or !elig.eligible) { redirect('/members/orders'); }
  setVariable('elig', elig);
</script>
```

The `getRefundEligibility()` function returns `null` if the order is not found, doesn't belong to the current customer, or is not eligible for a refund. The `eligible` flag is `false` when rules are not met (the `reasons` array describes why).

***

## Brand variables (`brand.*`)

The following brand-level variables are available in all templates:

| Variable | Type | Description |
| - | - | - |
| `brand.name` | string | Brand display name |
| `brand.code` | string | Brand code |
| `brand.currency` | string | Default currency code (e.g. `USD`) |
| `brand.timezone` | string | Brand timezone (e.g. `America/New_York`) |
| `brand.support_email` | string | Customer support email (from Brand Settings) |
| `brand.support_phone` | string | Customer support phone (from Brand Settings) |
| `brand.mbg_days` | number | Money-back guarantee window in days (0 = disabled) |

Use these in your templates:

```liquid theme={null}
@if(brand.support_email)
  <p>Need help? Email us at {{ brand.support_email }}</p>
@endif
```

***

## Template variables reference

### `getManageData(transactionId)`

Returns an object (or `null`):

| Field | Type | Description |
| - | - | - |
| `manage_enabled` | boolean | Always `true` when returned (null if disabled) |
| `retention_offers_enabled` | boolean | Whether retention offers are configured |
| `exit_survey_reasons` | string\[] | Exit survey reason keys |
| `offers` | object\[] | Retention offer rules |
| `subscription` | object | Subscription details (id, status, amount, frequency, etc.) |

### `getRefundEligibility(orderCode)`

Returns an object (or `null`):

| Field | Type | Description |
| - | - | - |
| `eligible` | boolean | Whether the order can be refunded |
| `reasons` | string\[] | Why the order is ineligible (empty when eligible) |
| `on_request_action` | string | `auto_refund`, `send_email`, or `create_ticket` |
| `order.conversion_code` | string | Conversion code (use as `order_id` in `requestRefund`) |
| `order.order_number` | string | Display order number |
| `order.total` | number | Order total |
| `order.remaining` | number | Remaining refundable amount |
| `order.currency` | string | Currency code |
| `order.created_at` | string | ISO date of purchase |

### Order fields (from `getOrders()`)

| Field | Type | Description |
| - | - | - |
| `order.refund_eligible` | boolean | Whether the order passes merchant-level refund rules |
| `order.conversion_code` | string | Conversion code (use as the order identifier for refund links) |
| `order.days_since_order` | number \| null | Number of full days since the order was placed |
| `order.fulfillment_status` | string \| null | Current fulfillment status (e.g. `shipped`, `fulfilled`, `delivered`) |

### `sub.manage_enabled` (subscriptions list)

The `getSubscriptions()` function includes `manage_enabled` on each subscription object. Use this to conditionally show the Manage button:

```liquid theme={null}
@if(sub.manage_enabled and sub.status eq 'active')
  <a href="/members/manage?tx={{ sub.original_transaction_id }}">Manage</a>
@endif
```

### Showing refund-eligible orders

Use `refund_eligible`, `days_since_order`, and `brand.mbg_days` together for the most accurate display:

```liquid theme={null}
@foreach(order in orders)
  @if(order.refund_eligible and not order.refund.fully_refunded)
    @if(brand.mbg_days lte 0 or order.days_since_order lt brand.mbg_days)
      <a href="/members/refund?order={{ order.conversion_code }}">Request refund</a>
    @endif
  @endif
@endforeach
```


# Members Login
Source: https://docs.elasticfunnels.io/members-area/login

Set up an email-based login page for your members area

The members login page lets returning customers access their purchases by entering the email they used at checkout. No password is needed — the system verifies their email against existing orders.

## How the Login Works

1. Customer enters their purchase email
2. The form POSTs to `/api/check-order`
3. The API looks up all purchase conversions for that email
4. If orders are found, the session is hydrated with customer data and the user is redirected
5. If no orders are found, an error message is shown

<Note>
  Customers who just completed a purchase are **already logged in** — their session is authenticated automatically at checkout. The login page is only needed for returning visitors whose session has expired.
</Note>

## Setting Up a Login Page

### Option 1: Use the Built-In Template

ElasticFunnels includes a pre-built **Members Login** page template. When creating a new page, select the "Members Login" template from the template picker. It comes with:

* Email input field
* Error/success message containers
* Submit button
* Styled card layout
* "Contact us" fallback link

### Option 2: Build a Custom Login Form

Create a form that POSTs to `/api/check-order` with the customer's email. The form needs three things:

1. **`action="/api/check-order"`** — The API endpoint
2. **`data-redirect-url="/your-members-page"`** — Where to send the customer after successful login
3. **Error/success message containers** — Elements with `data-form-error-message` and `data-form-success-message` attributes

### Minimal Example

```html theme={null}
<form action="/api/check-order" method="post" data-redirect-url="/members">
  <div hidden data-form-error-message></div>
  <div hidden data-form-success-message></div>

  <input type="email" name="email" required placeholder="your@email.com" />
  <button type="submit">Enter members area</button>
</form>
```

### Full Styled Example

```html theme={null}
<div class="max-w-md mx-auto p-8 bg-white rounded-2xl shadow-xl text-center">
  <h2 class="text-2xl font-bold mb-2">Members Area</h2>
  <p class="text-sm text-gray-500 mb-6">
    Enter the email address you used for purchase to access your order.
  </p>

  <div class="hidden mb-4 p-4 rounded-lg text-sm bg-red-100 text-red-800"
       data-form-error-message></div>
  <div class="hidden mb-4 p-4 rounded-lg text-sm bg-green-100 text-green-800"
       data-form-success-message></div>

  <form action="/api/check-order" method="post" data-redirect-url="/members">
    <input
      type="email"
      name="email"
      required
      placeholder="your@email.com"
      class="w-full px-4 py-3 rounded-lg border border-gray-300 mb-4"
    />
    <button type="submit"
            class="w-full bg-primary text-white font-bold py-3 rounded-xl">
      Enter members area
    </button>
  </form>

  <p class="text-sm text-gray-500 mt-4">
    Can't find your order?
    <a href="/contact" class="text-primary hover:underline">Contact us</a>
  </p>
</div>
```

## How the Form Submission Works

ElasticFunnels automatically intercepts any form whose `action` starts with `/api` and submits it via JavaScript (AJAX). You do not need to write any JavaScript — the built-in form handler:

1. Collects all form fields as JSON
2. POSTs to the `action` URL (`/api/check-order`)
3. On **success** (HTTP 200):
   * If `data-redirect-url` is set, redirects the customer to that URL
   * Otherwise, shows the `data-form-success-message` element with the server response
4. On **error** (HTTP 400):
   * Shows the `data-form-error-message` element with the error text
   * The submit button is re-enabled so the customer can try again

### Error Messages

The `/api/check-order` endpoint returns these errors:

| Error | Cause |
| - | - |
| `"Email is required"` | The email field was empty |
| `"Please enter a valid email address."` | The email format is invalid |
| `"We didn't find an order with that email address."` | No purchase conversions exist for that email |

## What Happens After Login

When login succeeds, the session is hydrated with data from the customer's most recent order:

* `session.email` — Set to the submitted email
* `session.customer` — Populated with name, email, phone, billing/shipping addresses, and all order IDs

This means any page that uses `{{ customer.name }}`, `{{ customer.email }}`, or the `<order>` tag / `getOrders()` function will now work correctly.

The customer is then redirected to the URL specified in `data-redirect-url` (typically your members dashboard page, e.g., `/members`).

## Configuring the Members Dashboard Page

Your members dashboard page (the page customers land on after login) should be configured with **Requires Login** enabled in page settings:

1. Open the members dashboard page in the editor
2. Go to **Page Settings**
3. Enable **Requires Login**
4. Set **Redirect URL** to `/members-login` (your login page slug)

This ensures that if someone tries to access the dashboard directly without a valid session, they are sent to the login page first.

## Logout

To let customers sign out, clear the session and redirect back to the login page:

```html theme={null}
<button onclick="if(confirm('Sign out?')){
  sessionStorage.clear();
  window.location.href='/members-login';
}">Sign Out</button>
```

<Tip>
  On thank-you pages, include a direct link to the members area (e.g., `<a href="/members">Access Member Area</a>`). Since the customer's session is already authenticated from checkout, they won't need to log in.
</Tip>


# Showing Order Details
Source: https://docs.elasticfunnels.io/members-area/order-details

Display order history, products, tracking, and shipping information in your members area

ElasticFunnels provides two ways to display order information on your pages: the `<order>` HTML tag (for the visual builder) and backend functions like `getOrders()` / `getOrder()` / `getSessionOrders()` / `getPurchasedProducts()` for code-based pages. Both retrieve data from the customer's purchase history.

## Two Approaches

| Approach | Best for | Used in |
| - | - | - |
| `<order>` tag | Visual builder pages, simple layouts | Drag-and-drop editor |
| `getOrders()` / `getOrder()` | Code-based pages, full order history | Backend scripts / `.ef` pages |
| `getSessionOrders()` | Thank-you pages — current purchase only | Backend scripts / `.ef` pages |
| `getPurchasedProducts()` | Member-area "library" pages — purchased products with their bonuses + downloads | Backend scripts / `.ef` pages |

<Tip>
  For a member-area page that needs **each purchased product with its included bonuses and download links**, prefer `getPurchasedProducts()` over manually joining `getOrders()` + `getAllProducts()` + `getBonusProducts()` on the client. It returns a flat list with same-order bonuses already attached and a pre-rolled-up `downloads[]` array (each entry tagged with `kind`). See the [data-functions reference](/backend-scripts/data-functions#getpurchasedproducts) and the ["My Library" pattern](/members-area/overview) for examples.
</Tip>

## Using the `<order>` Tag

The `<order>` tag is processed server-side and automatically loops through the customer's purchase history. See the full [Order Tag](/pages/order-tag) reference for all placeholders and options.

```html theme={null}
<order sort-by="newest" limit="5">
  <h3>Order #{order_number}</h3>
  <p>Date: {order_date}</p>
  <p>Shipping: {shipping_address}</p>

  <order-product>
    <img src="{product_image_url}" alt="{product_name}" />
    <p>{product_name} — {price}</p>
  </order-product>

  <order-bonus-product>
    <p>Bonus: {bonus_product_name}</p>
    <a href="{bonus_download}">Download</a>
  </order-bonus-product>
</order>
```

## Using `getOrders()` in Backend Scripts

For code-based pages (`.ef` files or pages with backend scripts), `getOrders()` gives you full control over the layout. It returns an array of order objects you can loop through with `@foreach`.

### Basic Usage

```html theme={null}
<script scope="backend">
var orders = getOrders('newest', 10);
setVariable('orders', orders);
</script>

@if(orders.length gt 0)
  @foreach(order in orders)
  <div class="order-card">
    <h3>Order #{{ order.order_number }}</h3>
    <p>{{ order.created_at | date:'dd, MMM yyyy' }}</p>

    @foreach(product in order.products)
    <div class="product-row">
      <img src="{{ product.image_url }}" alt="{{ product.name }}" />
      <span>{{ product.name }}</span>
      <span>{{ product.price | formatPrice:product.currency_code }}</span>
    </div>
    @endforeach
  </div>
  @endforeach
@else
  <p>No orders found.</p>
@endif
```

### Parameters (`getOrders`)

| Parameter | Type | Default | Description |
| - | - | - | - |
| `sortBy` | `string` | `'newest'` | Sort order: `'newest'` or `'oldest'` |
| `limit` | `number` | `50` | Maximum number of orders to return (max 1000) |

### Alternative: Inline Call

You can also call `getOrders()` directly in a `@set` directive without a backend script block:

```html theme={null}
@set(orders = getOrders('newest', 5))

@foreach(order in orders)
  <p>#{{ order.order_number }} — {{ order.created_at | date:'dd MMM yyyy' }}</p>
@endforeach
```

## Using `getOrder()` for a Single Order Detail Page

When you already know which order to show, use `getOrder(code)` instead of loading the full order list and searching manually. This is ideal for pages like `/members-order?order=EF-12345`.

`getOrder()` uses the same customer/session scope as `getOrders()`, so it only returns orders that belong to the currently logged-in customer for that brand.

### Example: Single order page

```html theme={null}
<script scope="backend">
var code = request.query.order;
var order = getOrder(code);
setVariable('order', order);
</script>

@if(order)
  <h1>Order #{{ order.order_number }}</h1>
  <p>{{ order.created_at | date:'dd MMM yyyy' }}</p>

  @foreach(product in order.products)
  <div>
    <span>{{ product.name }}</span>
    <span>{{ product.price | formatPrice:product.currency_code }}</span>
  </div>
  @endforeach
@else
  <p>Order not found.</p>
@endif
```

### What `code` can be

`getOrder(code)` matches any of these values within the current customer's orders:

* `order_number` / public order ID
* internal `order_id`
* conversion `code`

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `code` | `string` | Yes | Public order ID, internal order ID, or conversion code to match |

<Tip>
  For an order detail page, prefer `getOrder(request.query.order)` over `getOrders()` plus a manual loop/filter. It is shorter, clearer, and communicates intent directly.
</Tip>

## Fulfillment status and shipments

Use **`getOrderFulfillment(code)`** on an **order detail** page to show 3PL fulfillment status and timestamps. Responses are **allowlisted** (no raw provider payloads).

Use **`getOrderFulfillments()`** with **no arguments** to list **every** tracking row across **all** of the customer’s orders—each row includes `order_number` so you can link to `/members-order?order=…`.

For a **single** order, `order.tracking` from `getOrder` / `getOrders` is often enough for carrier links. The fulfillment helpers add **lifecycle status** (`getOrderFulfillment`) and a **cross-order shipment list** (`getOrderFulfillments`).

### Example: order detail with fulfillment summary

```html theme={null}
<script scope="backend">
var code = request.query.order;
setVariable('order', getOrder(code));
setVariable('fulfillment', getOrderFulfillment(code));
</script>

@if(fulfillment)
  <p>Fulfillment: {{ fulfillment.status }}</p>
  @if(fulfillment.sent_at)
    <p>Sent: {{ fulfillment.sent_at | date:'dd MMM yyyy' }}</p>
  @endif
@endif
```

### Example: all shipments for the account

```html theme={null}
<script scope="backend">
setVariable('shipments', getOrderFulfillments());
</script>

@if(shipments.length gt 0)
  @foreach(row in shipments)
  <div>
    <a href="/members-order?order={{ row.order_number }}">Order #{{ row.order_number }}</a>
    — {{ row.carrier }}: <a href="{{ row.tracking_url }}" target="_blank" rel="noopener">{{ row.tracking_number }}</a>
  </div>
  @endforeach
@endif
```

### Order Object Structure

Each order returned by `getOrders()` or `getOrder()` contains:

```javascript theme={null}
{
  order_number: "EF-12345",        // Public order ID
  created_at: "2026-03-15T...",    // ISO date string
  currency: "USD",                 // Order currency code

  // Billing address
  billing_address: "123 Main St",
  billing_city: "New York",
  billing_state: "NY",
  billing_zip: "10001",
  billing_country: "US",

  // Shipping address
  shipping_address: "123 Main St",
  shipping_address2: "",
  shipping_city: "New York",
  shipping_state: "NY",
  shipping_zip: "10001",
  shipping_country: "US",

  // Customer info
  customer_name: "John Doe",
  customer_email: "john@example.com",

  // Products array
  products: [
    {
      name: "Premium Course",
      image_url: "https://...",
      price: 97.00,
      quantity: 1,
      currency_code: "USD",
      is_bonus: false
    }
  ],

  // Tracking array (if fulfilled)
  tracking: [
    {
      tracking_number: "9400111899223456789012",
      tracking_url: "https://t.17track.net/en#nums=...",
      carrier: "USPS"
    }
  ]
}
```

## Displaying Tracking Information

If your orders have physical shipments, tracking information is automatically extracted from fulfillment data. The system checks multiple sources for tracking numbers:

1. Direct conversion fields (`tracking_number`, `tracking_url`)
2. Fulfillment provider response data
3. Fulfillment order data

Carriers are auto-detected from tracking number patterns (USPS, FedEx, UPS, DHL, UniUni). If no tracking URL is provided, a universal tracking link via 17track.net is generated.

`order.tracking` is always an array. When the order has not yet been fulfilled it is empty (`[]`). Use `order.shipping_address` as the signal that the order contains a physical product — if there is a shipping address but no tracking yet, show a "being processed" message.

### Example: Physical order with processing/tracking states

```html theme={null}
@set(orders = getOrders('newest', 5))

@foreach(order in orders)
<div class="order">
  <h3>Order #{{ order.order_number }}</h3>
  <p>{{ order.created_at | date:'dd MMM yyyy' }}</p>

  @if(order.shipping_address)
  <div class="shipping-address">
    <h4>Ships to</h4>
    <p>{{ order.shipping_address }}</p>
    <p>{{ order.shipping_city }}, {{ order.shipping_state }} {{ order.shipping_zip }}</p>
    <p>{{ order.shipping_country }}</p>
  </div>

  @if(order.tracking.length gt 0)
  <div class="tracking-info">
    <h4>Shipment Tracking</h4>
    @foreach(t in order.tracking)
    <div class="tracking-row">
      <span>{{ t.carrier }}</span>
      <a href="{{ t.tracking_url }}" target="_blank">{{ t.tracking_number }}</a>
    </div>
    @endforeach
  </div>
  @else
  <div class="tracking-pending">
    <p>Your order is being processed. Tracking information will appear here once your order ships.</p>
  </div>
  @endif

  @endif
</div>
@endforeach
```

The key pattern:

* `order.shipping_address` is present → physical product → show the shipping address block.
* Inside that block, `order.tracking.length gt 0` → shipment is on the way → show carrier + tracking link.
* Otherwise → show "Your order is being processed."

<Tip>
  Tracking numbers are auto-linked to [17track.net](https://17track.net) when no carrier URL is provided. The carrier is auto-detected from the number pattern (USPS, UPS, FedEx, DHL, UniUni). You do not need to map carriers yourself.
</Tip>

## `getSessionOrders()` — Current Session Orders

`getSessionOrders()` returns only the orders that were placed during the current browser session. Unlike `getOrders()`, which returns the full purchase history for a customer, `getSessionOrders()` is scoped to the active checkout session — making it the right choice for thank-you pages where you only want to show what was just bought.

The order list is served from the **session itself** — every charge (the main order, order bumps, and each one-click upsell/downsell) is recorded the instant it is processed. That means `getSessionOrders()` returns the **complete** set of orders on the very first page load, including upsells accepted seconds earlier. No indexing wait and no page refresh are required.

By default it returns **all** orders from the current session. Pass an optional `limit` to cap the count.

### Parameters (`getSessionOrders`)

| Parameter | Type | Default | Description |
| - | - | - | - |
| `sortBy` | `string` | `'newest'` | Sort order: `'newest'` or `'oldest'` |
| `limit` | `number` | *(all)* | Maximum number of orders to return; omit to return all session orders |

### Basic Usage

```html theme={null}
@set(orders = getSessionOrders())

@foreach(order in orders)
<div class="order-summary">
  <p>Order #{{ order.order_number }}</p>
  @foreach(product in order.products)
  <div>{{ product.name }} — {{ product.price | formatPrice:product.currency_code }}</div>
  @endforeach
</div>
@endforeach
```

<Tip>
  Prefer `getSessionOrders()` over `getOrders('newest', 1)` on thank-you pages. `getOrders()` reads from the search index, so a customer with an existing purchase history could see a previous order — or miss a just-accepted upsell — until the new conversions are indexed. `getSessionOrders()` reads from the current session, so it shows exactly what was just purchased, complete and immediately.
</Tip>

## Thank You Pages

Thank-you pages are a natural place to show order details. Since the customer is auto-authenticated from checkout, order data is available immediately.

Use **`getSessionOrders()`** on thank-you pages so that only the orders from the current checkout session are shown — not the customer's full history.

### Example: Thank You Page with Order Summary

```html theme={null}
@set(orders = getSessionOrders())

<h2>Order Confirmed!</h2>
<p>Thank you for your purchase.</p>

@if(orders.length gt 0)
  @foreach(order in orders)
  <div class="order-summary">
    <p>Order #{{ order.order_number }}</p>
    <p>Date: {{ order.created_at | date:'dd, MMM yyyy' }}</p>

    @foreach(product in order.products)
    <div class="product">
      <span>{{ product.name }}</span>
      <span>{{ product.price | formatPrice:product.currency_code }}</span>
    </div>
    @endforeach
  </div>
  @endforeach
@else
  <div class="processing">
    <p>We're finalizing your order. Check your email for your receipt, or visit your member area for full details.</p>
  </div>
@endif

<a href="/members">Access Member Area</a>
```

<Tip>
  No auto-refresh or retry timer is needed. `getSessionOrders()` serves the current session's orders from the session, so every order — including all upsells and bumps — is present on the **first** page load, with each order's primary product already shown. Full line-item detail (for example, an order bump attached to the main order) may enrich a moment later once the conversion finishes indexing, but the order rows and their primary products never wait on the index. Avoid a JavaScript refresh loop: it only re-runs a query that already returns the complete list.
</Tip>

## Customer Data Outside of Orders

You can also display customer information directly using the `customer` template object (populated from the session):

```html theme={null}
<p>Welcome back, {{ customer.name|default:"Member" }}!</p>
<p>Email: {{ customer.email }}</p>
```

The `customer` object includes: `name`, `email`, `first_name`, `last_name`, `phone`, `order_id`, `order_ids`, and full billing/shipping address fields. It is automatically available in every backend script and template — no function call needed.

## Order Grouping

Orders are grouped intelligently — multiple conversions from the same purchase session (e.g., a main product and an upsell bought in the same checkout flow) are combined into a single order. The grouping logic uses:

* **Session ID matching** — Conversions from the same browser session
* **Time proximity** — Conversions within 6 hours of each other

This means an upsell purchased immediately after the main product shows under the same order, not as a separate entry.

## Related Documentation

<CardGroup>
  <Card title="Order Tag Reference" icon="receipt" href="/pages/order-tag">
    Full reference for the `<order>` HTML tag and all placeholders
  </Card>

  <Card title="Backend Scripts" icon="terminal" href="/backend-scripts/overview">
    Learn about backend scripts and available functions
  </Card>

  <Card title="Template Engine Syntax" icon="code" href="/frontend-template-engine/syntax">
    Filters, conditionals, and loops for displaying data
  </Card>

  <Card title="Thank You Pages" icon="check-circle" href="/forms/thank-you-pages">
    Best practices for post-purchase confirmation pages
  </Card>
</CardGroup>


# Members Area
Source: https://docs.elasticfunnels.io/members-area/overview

Create password-free members areas where customers access their purchases, order history, and digital content

A Members Area lets your customers log in with their purchase email and access their orders, digital downloads, bonuses, and account information — no password required.

## How It Works

ElasticFunnels uses an email-based login system tied to purchase records. There are two ways a customer gets access:

1. **Automatic login after purchase** — When a customer completes checkout, their session is immediately authenticated. They can navigate to any members-only page without additional login.
2. **Email-based login** — Returning customers enter their purchase email on a login page. The system looks up their orders and grants access if a match is found.

```mermaid theme={null}
flowchart LR
    A[Customer buys product] --> B[Session auto-authenticated]
    B --> C[Access members pages]
    D[Returning customer] --> E[Enter purchase email]
    E --> F{Order found?}
    F -->|Yes| C
    F -->|No| G[Error: no order found]
```

## Key Components

A members area typically has three pages:

| Page | Purpose | Login required? |
| - | - | - |
| **Members Login** | Email form where returning customers identify themselves | No |
| **Members Dashboard** | Main content area with products, bonuses, order history | Yes |
| **Thank You** | Post-purchase confirmation with order details and members area link | No (auto-authenticated) |

<CardGroup>
  <Card title="Members Login" icon="lock" href="/members-area/login">
    Set up the email-based login form and configure redirects
  </Card>

  <Card title="Showing Order Details" icon="receipt" href="/members-area/order-details">
    Display order history, products, tracking, and shipping info
  </Card>
</CardGroup>

## Auto-Login After Purchase

When a customer completes a purchase through ElasticFunnels checkout, the system automatically:

1. Sets `is_customer = true` on their session
2. Stores their email, name, billing/shipping addresses, and order IDs in the session
3. Marks them as an authenticated customer

This means **thank-you pages and members pages work immediately** after checkout — the customer never needs to enter their email again during that browser session.

The session stores the following customer data automatically:

| Field | Description |
| - | - |
| `customer.name` | Full name from checkout |
| `customer.email` | Email address |
| `customer.first_name` | First name |
| `customer.last_name` | Last name |
| `customer.phone` | Phone number (if collected) |
| `customer.order_id` | Most recent order ID |
| `customer.order_ids` | All order IDs for this customer |
| `customer.billing_*` | Billing address fields |
| `customer.shipping_*` | Shipping address fields |

## Protecting Pages with Login

There are two ways to restrict a page to logged-in customers only.

### Option 1: Page setting (recommended)

1. Open the page settings in the editor
2. Enable **Requires Login**
3. Set the **Redirect URL** to your login page (e.g., `/members-login`)

When a visitor without a valid session tries to access the page they are automatically redirected to that URL. If no redirect is configured, a 404 page is shown.

### Option 2: Backend scope script

Add a `<script scope="backend">` block at the top of the page. This gives you more control — for example, redirecting to different pages based on the customer's order history or preserving a `?next=` query parameter.

```html theme={null}
<script scope="backend">
  if (!is_customer) {
    redirect('/members-login');
  }
</script>
```

You can pass the current path as a query parameter so the login page can redirect back after a successful login:

```html theme={null}
<script scope="backend">
  if (!is_customer) {
    redirect('/members-login?next=' + encodeURIComponent(request.path));
  }
</script>
```

`is_customer` is `true` when the visitor has an active session from a purchase or from the email login form. See [Request Context](/backend-scripts/context) for all available globals and [Actions](/backend-scripts/actions) for the full `redirect()` reference.

When a customer has a valid session (either from a purchase or from the login form), the script does nothing and the page renders normally.

## Auth Wrapper Pattern (recommended)

When your members area has more than one page — dashboard, order history, bonuses, course access, account settings — the recommended approach is an **auth wrapper**: a shared layout or script block that handles the authentication check and loads common data in one place. Every members page extends or includes the wrapper, so you never repeat the login redirect logic.

### For `.ef` template files — `@extends`

Create a `members-layout.ef` that handles auth and prefetches common data:

```html theme={null}
{{-- members-layout.ef --}}
<script scope="backend">
  if (!is_customer) {
    redirect('/members-login');
  }
  var orders = getOrders('newest', 20);
  var bonuses = getBonusProducts();
  setVariable('orders', orders);
  setVariable('bonuses', bonuses);
</script>
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>@block("title") Members Area @endblock</title>
</head>
<body>
  <header>
    <span>Welcome, {{ customer.first_name | default:"Member" }}</span>
    <nav>
      <a href="/members">Dashboard</a>
      <a href="/members/orders">Orders</a>
      <a href="/members/bonuses">Bonuses</a>
    </nav>
  </header>
  @block("content") @endblock
</body>
</html>
```

Every members page extends it — no auth logic needed per page:

```html theme={null}
{{-- members-dashboard.ef --}}
@extends("members-layout")
@block("title") Dashboard @endblock
@block("content")
<h1>Your Orders</h1>
@foreach(order in orders)
  <p>#{{ order.order_number }} — {{ order.created_at | date:'dd MMM yyyy' }}</p>
@endforeach
@endblock
```

```html theme={null}
{{-- members-bonuses.ef --}}
@extends("members-layout")
@block("title") Bonuses @endblock
@block("content")
<script scope="backend">
  var bonuses = getBonusProducts();
  setVariable('bonuses', bonuses);
</script>
<h1>Your Bonuses</h1>
@if(var.bonuses.length > 0)
  @foreach(bonus in var.bonuses)
    <div class="bonus-card">
      <img src="{{ bonus.image_url }}" alt="{{ bonus.title }}" />
      <h3>{{ bonus.title }}</h3>
      <p>{{ bonus.description }}</p>
      @if(bonus.bonus_url)
        <a href="{{ bonus.bonus_url }}">Download</a>
      @endif
    </div>
  @endforeach
@else
  <p>No bonus products yet.</p>
@endif
@endblock
```

### "My Library" pattern — `getPurchasedProducts()`

For member-area pages that show **everything the customer owns** (purchased products + the bonuses they came with + download links), use `getPurchasedProducts()`. It returns a flat list with full catalog data, same-order bonuses already attached under `included_bonuses[]`, and a pre-rolled-up `downloads[]` array tagged by `kind` (`'audio'`, `'video'`, `'document'`, `'image'`, `'archive'`, `'file'`).

```html theme={null}
{{-- members-library.ef --}}
@extends("members-layout")
@block("title") My Library @endblock
@block("content")
<script scope="backend">
  var library = getPurchasedProducts('newest');
  setVariable('library', library);
</script>

<h1>My Library</h1>
@foreach(item in var.library)
  <article class="library-card">
    <img src="{{ item.image }}" alt="{{ item.title }}" />
    <h2>{{ item.title }}</h2>
    <p class="meta">Order #{{ item.order_number }} — {{ item.created_at | date:'dd MMM yyyy' }}</p>

    {{-- Downloads (pre-rolled-up, deduped, kind-tagged) --}}
    @if(item.downloads.length > 0)
      <ul class="downloads">
        @foreach(d in item.downloads)
          <li>
            <a href="{{ d.url }}">
              <span class="kind">{{ d.kind }}</span> {{ d.title | default:'Download' }}
              @if(d.extension)<small>.{{ d.extension }}</small>@endif
            </a>
          </li>
        @endforeach
      </ul>
    @endif

    {{-- Included bonuses (attached to THIS order — every is_bonus line) --}}
    @if(item.included_bonuses.length > 0)
      <section class="bonuses">
        <h3>Included Bonuses</h3>
        @foreach(b in item.included_bonuses)
          <div class="bonus">
            <h4>{{ b.title }}</h4>
            @if(b.bonus_url)
              <a href="{{ b.bonus_url }}">Download</a>
            @endif
          </div>
        @endforeach
      </section>
    @endif
  </article>
@endforeach
@endblock
```

<Tip>
  Use `getPurchasedProducts()` for a member-area "library" view that needs to know **which bonuses came with which purchase**. It joins orders → catalog → bonuses on the server and returns ready-to-render data. For a flat list of bonuses the customer is entitled to (no parent product context), `getBonusProducts()` is still the right call.
</Tip>

### For page builder pages — shared script block

Paste the same backend script at the top of every protected page. Because it always does the same work, any change only needs to happen in one shared spot (consider using a page component for the header/nav):

```html theme={null}
<script scope="backend">
  if (!is_customer) {
    redirect('/members-login');
  }
  var orders = getOrders('newest', 20);
  setVariable('orders', orders);
</script>

<h1>Welcome, {{ customer.first_name | default:"Member" }}</h1>
```

<Tip>
  Load only what each page needs. The dashboard might call `getOrders('newest', 5)`, while the full order-history page calls `getOrders('newest', 100)`. The wrapper sets a sensible default; individual pages can override `orders` by calling `setVariable` again after the wrapper runs.
</Tip>

## Template Variables

Inside members-only pages, you can use the `customer` object to personalize content:

```html theme={null}
<h1>Welcome, {{ customer.first_name|default:"Member" }}!</h1>
<p>Your account email: {{ customer.email }}</p>
<p>Order ID: {{ customer.order_id }}</p>
```

See [Showing Order Details](/members-area/order-details) for how to display full order history with products and tracking.


# Subscription Management Page
Source: https://docs.elasticfunnels.io/members-area/subscription-management

Build a members-area page where customers can see, change and cancel their subscriptions, and record why they left.

A subscription management page lists a customer's plans and lets them cancel one.
This page is the only place a cancellation reason can come from, so it is worth
building properly: without it your churn reporting can only ever say "Not
specified".

Enable **Manage** first in **Merchant settings → Customer care**. Without it the
helpers below return nothing.

## Listing subscriptions

`getSubscriptions(status, limit)` returns the logged-in customer's subscriptions.
Call it once per status you want to show.

```twig theme={null}
@set(active_subs = getSubscriptions('active', 20))
@set(canceled_subs = getSubscriptions('canceled', 20))

@foreach(sub in active_subs)
  <div class="plan">
    <strong>{{ sub.product_name }}</strong>
    <small>{{ sub.amount | currency }} every {{ sub.frequency }} {{ sub.frequency_unit }}</small>
    <button type="button" data-cancel="{{ sub.original_transaction_id }}">Cancel</button>
  </div>
@endforeach
```

Each subscription carries `original_transaction_id`, which identifies it to every
call below. Keep it on the button.

## Asking why, before cancelling

`cc.getManageData(transactionId)` returns what the customer is allowed to do,
including `exit_survey_reasons` - the list to put in your dropdown.

```js theme={null}
cc.getManageData(transactionId).then(function (data) {
  data.exit_survey_reasons.forEach(function (reason) {
    var option = document.createElement('option');
    option.value = reason;
    option.textContent = labelFor(reason);
    select.appendChild(option);
  });
});
```

If the merchant has not configured its own list, you get the standard set:

| Key | Meaning |
| - | - |
| `too_expensive` | Price |
| `not_using` | Low engagement |
| `results` | Did not work for them |
| `side_effects` | Reaction to the product |
| `too_much_product` | Oversupplied, often a shipping-frequency problem |
| `temporary_pause` | Wants to come back |
| `found_alternative` | Went to a competitor |
| `other` | Anything else |

These keys are identifiers, not copy. Show your own wording to the customer and
send the key back.

`temporary_pause` and `too_much_product` are worth watching: both usually mean the
plan interval is wrong rather than the product being wrong, and both are
recoverable with a retention offer.

## Cancelling, with the reason attached

Pass the selected reason as the second argument. **This is the step that is easy
to miss, and missing it silently costs you the whole survey** - the cancellation
still succeeds, so nothing looks broken, and every row in your Cancel Reasons
report reads "Not specified".

```js theme={null}
var reason = document.getElementById('cancel-reason').value || null;
window.ef.sub.cancelThenNavigate('/members-subscriptions?canceled=1', reason);
```

Use `ef.sub.cancel(reason)` instead if you want to stay on the page and handle the
result yourself. Both accept the reason; both work without it.

## Offering something before they go

If retention offers are enabled, `getManageData` also returns `offers`. An offer
can be matched to the reason the customer picked, so a price complaint gets a
discount and an oversupply complaint gets a longer interval.

```js theme={null}
var offer = data.offers.find(function (o) { return o.cancel_reason === reason; });

cc.applyOffer({
  transactionId: transactionId,
  offerType: offer.offer_type,
  offerValue: offer.offer_value,
  durationCycles: offer.offer_duration_cycles,
  productCode: offer.offer_product_code,
  cancelReason: reason
});
```

See [Retention Offers](/subscriptions/retention-offers) for configuring them.

## Checking it worked

Cancel a test subscription, choose a reason, then open **Reports → Subscriptions**
and look at the Cancel Reasons card. The reason should appear by name within a
minute or two.

If it says "Not specified", the reason is not reaching the server. In almost every
case that is the second argument missing from `cancelThenNavigate`.


# Apple Pay and Google Pay
Source: https://docs.elasticfunnels.io/merchants/apple-pay-google-pay

Enable and configure Apple Pay and Google Pay on your checkout (NMI or Stripe)

Apple Pay and Google Pay are payment options on your checkout. They work with both **NMI** and **Stripe** merchants. No separate merchant account is required. Card checkout remains available if a wallet is not shown or the customer cancels.

## Overview

* **Apple Pay** - Appears on **Safari** (macOS and iOS) when the customer has Apple Pay set up. Setup depends on your gateway (see below).
* **Google Pay** - Appears on supported browsers when a Google Pay wallet is available. With NMI it appears on **Android devices** only. With Stripe it can also appear on **desktop Chrome**.
* Both options appear on the **checkout page** only. By default they render inside `<checkout-cc-panel>`, or you can place them anywhere on the page with `<checkout-wallet />`.

## How to configure / enable

Setup differs by gateway. Choose your gateway below.

***

### Stripe

#### Google Pay (Stripe)

No configuration is required beyond domain registration (see Apple Pay step below). Google Pay appears automatically on checkout when the customer has a Google Pay wallet. With Stripe, Google Pay can appear on **desktop Chrome** in addition to Android devices.

#### Apple Pay (Stripe)

Stripe handles Apple's merchant validation behind the scenes. You do **not** need to create an Apple Merchant ID, CSR, or host a `.well-known` verification file. Follow these steps:

**Step 1: Make sure your Stripe account is in live mode**

<Warning>
  Apple Pay **only works with live Stripe API keys**. If your Stripe merchant is using test-mode keys, Apple Pay will not appear - `canMakePayment()` returns `null` and the button is silently hidden. Switch to **live mode** in the Stripe Dashboard and use your live publishable key on the checkout domain.
</Warning>

**Step 2: Register your checkout domain(s) with Stripe**

1. In the [Stripe Dashboard](https://dashboard.stripe.com), make sure you are in **live mode** (toggle at the top of the dashboard).
2. Go to **Settings** → [**Payment method domains**](https://dashboard.stripe.com/settings/payment_method_domains).
3. Click **Add a new domain**.
4. Enter the exact domain customers use at checkout (e.g. `checkout.yourstore.com`).
5. Click **Save and continue**.
6. Repeat for any additional domains or subdomains (including `www`).

<Note>
  Domains registered in **live mode** are automatically available in sandbox/test mode as well. For local testing, use a tool like [ngrok](https://ngrok.com/) to get an HTTPS domain and register that. However, Apple Pay itself still requires live keys to appear on supported devices.
</Note>

After registering with live keys, Apple Pay appears on checkout when the customer uses Safari on macOS or iOS and has Apple Pay configured. No verification file is needed - Stripe takes care of it.

For more details, see [Stripe's domain registration guide](https://docs.stripe.com/payments/payment-methods/pmd-registration) and [Apple Pay on the web](https://docs.stripe.com/apple-pay?platform=web).

***

### NMI

#### Google Pay (NMI)

No configuration is required.

1. Ensure the domain uses an **NMI** merchant.
2. Ensure that merchant uses **tokenization** (Collect.js): in the merchant settings, tokenization mode should be **Collect.js** and the **public / tokenization key** should be set.
3. Assign that NMI merchant to your checkout domain under **Settings** → **Domains** → **Edit Domain** → **Merchant**.

Google Pay appears automatically on checkout when the customer is on an **Android device** with a supported browser (Chrome). It does not appear on desktop browsers.

#### Apple Pay (NMI)

**Prerequisites:** NMI merchant with tokenization (Collect.js), and the checkout domain linked to that merchant (as above).

**Step 1: Enable Apple Pay in NMI**

1. Log in to the [NMI Merchant Portal](https://secure.nmi.com/merchants/).
2. Go to **Settings** → **Apple Pay**.
3. Enable Apple Pay for your account (if your processor supports it).

**Step 2: Register your checkout domain(s) with NMI**

NMI must have a list of domains that are allowed to show Apple Pay. Use the same domain(s) that serve your checkout in ElasticFunnels (e.g. the domain you set under **Settings** → **Domains**).

* In the NMI Merchant Portal, add your checkout domain(s) to the Apple Pay allowed list (see NMI's Apple Pay / domain registration section).
* If ElasticFunnels later adds an in-app "Register domains" action for your NMI merchant, you can use that to sync your linked domains; otherwise configure the list in NMI's portal.

**Step 3: Apple domain verification**

Apple requires a verification file on your checkout domain. NMI provides this file.

1. Download the **domain verification file** from NMI (in the NMI Merchant Portal under the Apple Pay settings, or from Apple's developer resources as NMI directs you).
2. Host it at:\
   `https://<your-checkout-domain>/.well-known/apple-developer-merchantid-domain-association`\
   Replace `<your-checkout-domain>` with the exact domain customers use at checkout (e.g. `checkout.yourstore.com`).
3. Ensure the file is publicly accessible over HTTPS. **Recommended:** In the app, go to **Domains** → edit the checkout domain → **Apple Pay** tab, and paste the exact contents of the verification file. The offer site will then serve it at `/.well-known/apple-developer-merchantid-domain-association` for that domain. Alternatively, you can set the env var **`APPLE_PAY_DOMAIN_VERIFICATION_CONTENT`** on the offer server as a fallback (same content for all domains on that server). If neither is set, the path returns 404 and you must host the file elsewhere.

After all three steps, Apple Pay can appear on checkout when the customer uses Safari on macOS or iOS and has Apple Pay configured.

## Placement options

There are three ways to include Apple Pay / Google Pay on your checkout page:

### Default - wallet tab inside the card panel

```html theme={null}
<checkout-cc-panel data-accepted-cards="visa,mastercard,amex,discover"></checkout-cc-panel>
```

On an HTTPS page with an NMI or Stripe merchant, the panel renders Apple Pay as a **radio tab** alongside Card (and PayPal / Klarna when configured). The tab relabels itself to Google Pay if Google Pay is detected instead.

The older inline layout - wallet buttons above the card fields with an `or pay with card` divider - is only used as a fallback when the tab layout is unavailable (non-HTTPS page, an unsupported gateway, or an `#applePay` container already on the page from `<checkout-wallet>`).

### Standalone - wallet buttons anywhere on the page

Use `<checkout-wallet />` to place the wallet buttons wherever you want, and disable them inside the card panel with `data-applepay="false"`:

```html theme={null}
<!-- Wallet buttons at the top of the checkout, before the form -->
<checkout-wallet force="true" wallets="apple_pay,google_pay" />

<!-- Card-only panel below -->
<checkout-cc-panel data-accepted-cards="visa,mastercard,amex,discover" data-applepay="false"></checkout-cc-panel>
```

This renders `<div class="ef-wallet-standalone">` containing both the `#applePay` and `#googlePay` containers. Because the panel skips its own wallet tab whenever an `#applePay` element already exists, adding `<checkout-wallet>` is enough on its own - but `data-applepay="false"` keeps the intent explicit.

| Attribute | Values | Effect |
| - | - | - |
| `force` | `"true"` | Pre-renders a native `<apple-pay-button>` placeholder so iOS shows it immediately, and sets `checkout.wallet_visible` to `true` right away instead of waiting for detection. |
| `wallets` | `apple_pay`, `google_pay` (comma-separated) | Restricts which wallets are allowed. Passed to the client as `data-wallets` and used for Stripe's `disableWallets`. |

Both attributes are plain attributes, **not** `data-` prefixed. The tag may be written self-closing (`<checkout-wallet />`) or with an explicit closing tag.

<Note>
  `<checkout-apple-pay />` is the legacy single-wallet version of this tag. It still works and accepts `force="true"`, but it only ever renders the Apple Pay container. Prefer `<checkout-wallet />` for new pages.
</Note>

### Disable wallet buttons in the card panel

```html theme={null}
<checkout-cc-panel data-accepted-cards="visa,mastercard,amex,discover" data-applepay="false"></checkout-cc-panel>
```

Apple Pay is not rendered inside the panel.

<Warning>
  `data-applepay="false"` does **not** always suppress Google Pay. On **NMI** merchants, a `#googlePay` container is still injected into the panel when the visitor is on an Android device, so a Google Pay button can still appear. On **Stripe** merchants both wallets share the same mount point, so `data-applepay="false"` disables both.
</Warning>

<Note>
  `data-applepay-layout` is read by the client-side panel, but the server-side tag expander does not forward it: `<checkout-cc-panel>` is rewritten into a `<div class="checkout-cc-panel">` carrying only `data-gateway`, `data-accepted-cards`, `data-applepay` and `data-applepay-force`. Writing `data-applepay-layout="separated"` on the tag therefore has **no effect** - use `<checkout-wallet />` for an above-the-panel wallet instead.
</Note>

## Conditional display

Two scope variables drive wallet-aware layouts:

| Key | Set by | Shape | Notes |
| - | - | - | - |
| `checkout.wallet_available` | Server-side as `{ applePay: false, googlePay: false }`, then updated client-side once the payment library detects support | `{ applePay, googlePay }` | Use for "which wallet does this visitor have" |
| `checkout.wallet_visible` | Client-side by the payment panel when a wallet button is actually rendered | boolean | Only ever promoted from `false` to `true`, never reset. `<checkout-wallet force="true">` sets it immediately |

Use them to show or hide parts of your checkout layout:

```html theme={null}
<!-- Wallet buttons - always in the DOM, buttons fill in when supported -->
<checkout-wallet force="true" />

<!-- Divider only once a wallet button is actually showing -->
<template-if data-condition="checkout.wallet_visible">
  <div class="or-divider">or pay another way</div>
</template-if>

<!-- Personal details: the tag generates its own fields -->
<checkout-personal-details data-fields="email,phone"></checkout-personal-details>

<!-- Card panel (no wallet inside it) -->
<checkout-cc-panel data-accepted-cards="visa,mastercard,amex,discover" data-applepay="false"></checkout-cc-panel>
```

<Warning>
  `<checkout-personal-details>` **generates** its name / email / phone inputs from `data-fields` - you do not write them yourself. Any HTML you place inside the tag is preserved, but it is appended **after** the generated fields, not used in place of them. The same applies to `<checkout-details>` for shipping and billing. `<checkout-cc-panel>` discards its children entirely.
</Warning>

<Note>
  `checkout.wallet_available` starts as `{ applePay: false, googlePay: false }` and is only updated after the payment library loads and detects wallet support (NMI Collect.js or Stripe.js). This can take 1-2 seconds after page load, so a `template-if` on it will briefly evaluate false on first paint. Prefer `checkout.wallet_visible` (or `<checkout-wallet force="true">`) when you need the layout stable immediately.
</Note>

### Example: wallet-first checkout

This layout shows the wallet buttons prominently at the top, with the card form below:

```html theme={null}
<div style="text-align:center; padding: 24px 0;">
  <h3>Quick checkout</h3>
  <checkout-wallet force="true" wallets="apple_pay,google_pay" />
</div>

<template-if data-condition="checkout.wallet_visible">
  <p style="margin-top: 12px; color: #6b7280; font-size: 14px;">
    Or pay another way
  </p>
</template-if>

<div class="floating-label-group">
  <input type="email" name="email" data-template-value="checkout.customer.email" />
  <div class="form-error" data-checkout-error="email"></div>
</div>

<checkout-cc-panel data-accepted-cards="visa,mastercard,amex,discover" data-applepay="false"></checkout-cc-panel>

<div data-checkout-message class="checkout-message"></div>
<button type="button" data-checkout-submit>Pay now</button>
```

## How wallet payment works

When a customer taps the Apple Pay or Google Pay button:

1. The native wallet sheet appears (Face ID / Touch ID for Apple Pay, or Google Pay authentication).
2. The wallet provides the payment token **and** contact data (name, address, email, phone).
3. The system automatically fills the checkout form fields with the wallet data.
4. The form auto-submits. No further action from the customer.

This means the customer can skip filling out the checkout form entirely. The wallet provides everything needed for the payment. Personal, shipping and billing form fields are only filled when they are currently **empty** - the one exception is `shipping_country` / `billing_country`, which are always overwritten with the wallet's value.

## Wallet contact field auto-detection

<Note>
  This auto-detection applies to **NMI / Collect.js** checkouts only. On **Stripe**, the payment request is created with `requestPayerName`, `requestPayerEmail` and `requestShipping` always enabled and no phone request, regardless of which fields are on the page.
</Note>

On NMI, the wallet detects which contact fields to request based on which checkout fields are on the page. No explicit configuration is needed.

| Page has | Wallet requests |
| - | - |
| Shipping address fields (`shipping_address`, `shipping_country`) | Shipping postal address |
| Billing address fields (`billing_address`, `billing_country`) | Billing postal address |
| A first-name field (`first_name`, `shipping_first_name`, or `billing_first_name`) | Name |
| `email` field | Email |
| `phone` field | Phone |
| None of the above | No contact fields - payment token only |

Only the **first-name** variants are checked. A page carrying `last_name` without any `*_first_name` field does not trigger the name request.

**Digital product example:** A checkout page with only email and a payment panel (no name or address fields) causes Apple Pay to request only the customer's email. This is ideal for digital goods where shipping details are unnecessary.

```html theme={null}
<div class="floating-label-group">
  <input type="email" name="email" data-template-value="checkout.customer.email" />
</div>
<checkout-cc-panel data-accepted-cards="visa,mastercard,amex,discover"></checkout-cc-panel>
<button type="button" data-checkout-submit>Purchase</button>
```

## Subscriptions and recurring payments

When a customer purchases a **subscription** using Apple Pay or Google Pay, the system stores the payment method for future use:

* **NMI:** A **customer vault entry** is created during the initial charge. All subsequent subscription charges (renewals, rebills) use this vault entry server-to-server. **Requires Customer Token Vault — see below.**
* **Stripe:** The **PaymentMethod** is saved to the Stripe customer with `setup_future_usage: 'off_session'`. All subsequent charges use this stored payment method server-to-server.

No additional customer interaction is needed for renewals. The subscription billing schedule is managed entirely on the server. The wallet token is consumed on the first charge, and the stored method handles everything after that.

<Warning>
  **NMI wallet subscriptions need Customer Token Vault switched on before they will renew.**

  Apple Pay hands the gateway a **single-use device token (DPAN)**. That token is bound to
  the cryptogram issued for that one transaction — it cannot be charged again on its own.
  The initial payment therefore succeeds while every renewal declines, which usually shows
  up weeks later as a cohort of failed rebills rather than an obvious error at checkout.

  For renewals to work, the merchant account needs **Customer Token Vault / network
  tokenisation** enabled at NMI so the gateway can store a reusable merchant token (MPAN)
  instead of the device token. This is an **opt-in** feature — ask your NMI representative
  or ISO to activate it. ElasticFunnels then declares the transaction as recurring on the
  initial authorization so Apple issues a reusable credential.

  **Verify with one real renewal before you scale spend on a wallet subscription offer.**
  Take a live Apple Pay subscription and force a rebill. A green toggle in the merchant
  settings is not sufficient proof on its own — the check degrades open, so it can report
  success on an account that has not had network tokenisation activated.
</Warning>

### Checking whether a wallet subscription will renew

| Check | Where | What you want to see |
| - | - | - |
| Customer Token Vault active | NMI merchant account (via your rep or ISO) | Enabled — it is opt-in and off by default |
| Stored credential created | Transaction record after the first charge | A `customer_vault_id` is present (NMI) or a stored `payment_method` on the customer (Stripe) |
| Renewal actually settles | One live forced rebill | Approved, with no customer interaction |

If the first charge succeeds but no `customer_vault_id` is recorded, the subscription will
not renew. Fix the vault configuration before sending traffic rather than after.

## One-click upsells

When a customer pays with Apple Pay or Google Pay on the main checkout, the payment method is stored for reuse. Subsequent **one-click upsell** charges on the same funnel use this stored method server-to-server. No additional customer interaction is needed. The customer sees upsell pages and clicks "Yes, add this" as usual; the charge happens instantly.

This works the same as card-based one-click upsells for both NMI and Stripe.

## Billing address handling

When a customer pays with Apple Pay or Google Pay, the wallet provides the **correct billing address** associated with the card. The wallet's billing values always overwrite the internal `checkout.customer.billing_*` scope object, so the address used for verification (AVS) comes from the wallet rather than from anything typed earlier. This prevents address verification mismatches and declined payments.

No configuration is needed. This is handled automatically.

<Note>
  The scope object and the form inputs behave differently. `checkout.customer.billing_*` is always replaced with the wallet address, but the corresponding **form fields** are only overwritten when they were empty (`billing_country` and `shipping_country` excepted - those are always replaced). On a page that shows editable billing address inputs above the wallet button, a value the customer already typed is what gets submitted.
</Note>

<Note>
  For non-US addresses, Apple Pay may not return a state/region value (many countries don't use states in their address format). The checkout validation automatically skips state validation for wallet payments, so this does not cause errors.
</Note>

## Troubleshooting

### Apple Pay button does not show

**Stripe:**

* **Confirm you are using live API keys.** Apple Pay does not appear when the Stripe merchant is in test mode. This is the most common cause of Apple Pay not showing with Stripe. Switch to live mode in the Stripe Dashboard and ensure your checkout domain is using the **live publishable key**.
* Confirm the domain is registered in the Stripe Dashboard under [Payment method domains](https://dashboard.stripe.com/settings/payment_method_domains) and shows as **Enabled**. Make sure you registered the domain in **live mode**.
* Check that the customer is on **Safari** (macOS or iOS) and the page is served over **HTTPS**.
* No `.well-known` verification file is needed for Stripe. Stripe handles merchant validation. If you previously used NMI and have a verification file on the domain, it does not interfere.
* If using `<checkout-wallet />` or `<checkout-apple-pay />`, make sure the tag is on the page.

**NMI:**

* Confirm the domain uses an NMI merchant with **Collect.js** (tokenization) and a public/tokenization key.
* Check that the customer is on **Safari** (macOS or iOS) and the page is served over **HTTPS**.
* Confirm the domain is registered with NMI for Apple Pay and that the Apple verification file is reachable at `https://<your-checkout-domain>/.well-known/apple-developer-merchantid-domain-association`.
* If using `<checkout-wallet />` (or legacy `<checkout-apple-pay />`), make sure the tag is on the page (it renders a container; the button appears inside it when supported).
* If you set `data-applepay-layout` on `<checkout-cc-panel>` and nothing changed, that is expected - the attribute is dropped during server-side expansion. Use `<checkout-wallet />` instead.

### Google Pay button does not show

* **NMI:** Google Pay only appears on **Android devices**. It does not show on desktop Chrome or other desktop browsers. Confirm the domain uses an NMI merchant with **Collect.js** (tokenization) and a public/tokenization key.
* **Stripe:** Google Pay can appear on desktop Chrome as well as Android. Confirm the domain is registered under [Payment method domains](https://dashboard.stripe.com/settings/payment_method_domains).

### Verification file not found (NMI / Apple Pay)

* Ensure the file is at the exact `.well-known` path and that the domain matches the one used at checkout.
* If you use a subdomain for checkout, that subdomain must be the one registered with NMI and Apple and must serve the verification file.
* **This does not apply to Stripe** - Stripe handles verification without a hosted file.

### Other issues

* **Wallet payment cancelled or failed** - The customer can pay with card instead; the card form remains available. No page reload is required.
* **State/region error on wallet payment** - This should be handled automatically. If you see state validation errors after a wallet payment, ensure you are on the latest version of the checkout plugin.
* **Subscription charges fail after initial wallet purchase** - Verify the payment created a stored payment method. For NMI, check the transaction record for a `customer_vault_id`. For Stripe, check for a stored `payment_method` on the customer.
* **One-click upsell charges fail after wallet payment** - Same as above - ensure the payment method was stored during the initial charge.

For more on NMI and Apple Pay, see [NMI's documentation](https://docs.nmi.com/docs/collectjs) and [Digital Wallet Setup](https://docs.nmi.com/docs/digital-wallet-setup). For Stripe, see [Stripe's Apple Pay guide](https://docs.stripe.com/apple-pay?platform=web) and [domain registration](https://docs.stripe.com/payments/payment-methods/pmd-registration).


# Buygoods
Source: https://docs.elasticfunnels.io/merchants/buygoods

Set up Buygoods as a merchant, assign to a domain, and map products

This guide explains how to set up Buygoods as a merchant. The overall flow matches the generic merchant setup; use this page for Buygoods-specific notes.

## Step 1: Create Buygoods Merchant

1. Go to **Settings** → **Merchants** → **Add Merchant**
2. Select **Gateway**: Buygoods
3. Enter your **Account ID** as provided by Buygoods
4. Save

## Step 2: Assign Merchant to Domain

1. Go to **Settings** → **Domains** → **Edit Domain**
2. Select your Buygoods merchant
3. Save

## Step 3: Map Products

1. Go to **Settings** → **Products** → **Edit**
2. Open the **Merchant information** tab
3. Enter the **Buygoods Product ID** for this product
4. Save

## Links and Funnels

Use `[BUY]`, `[UPSELL]`, and `[DOWNSELL]` tags so links auto-adapt per domain and merchant. Avoid pasting hardcoded Buygoods checkout URLs.

* See [How to set up a new merchant](/guides/how-to-set-up-a-new-merchant)
* See [Buy Links](/products/buy-links)
* See [Advanced Purchase Links](/products/advanced-purchase-links)

## Postbacks

Use the **Setup** modal in the **Merchants** list for up-to-date postback instructions and your unique URL. After you configure the URLs in Buygoods and send a test (or run a test purchase), the modal will automatically mark the connection as validated once the webhook is received.

## Troubleshooting

* Wrong gateway on checkout: Verify the domain is assigned to Buygoods
* Link not working: Ensure product mapping has the correct Buygoods Product ID
* Missing affiliate data: Confirm affiliate sync settings and use adaptive tags


# ClickBank
Source: https://docs.elasticfunnels.io/merchants/clickbank

Set up ClickBank as a merchant, including pitch flow and domain assignment

This guide covers setting up ClickBank as a merchant to sell your products through the ClickBank marketplace, including pitch flow configuration and merchant setup.

<Note>This is for merchants selling through ClickBank. If you're an affiliate promoting ClickBank products, see the [ClickBank Affiliate Integration](/integrations/clickbank) instead.</Note>

## Prerequisites

* Active ClickBank account with vendor access (ClickBank term)
* Approved products in ClickBank marketplace
* Admin access to your ClickBank account
* Understanding of ClickBank pitch flow system

## Step 1: Create ClickBank Merchant

### Add Merchant Configuration

1. Go to **Settings** → **Merchants** → **Add Merchant**
2. Select **Gateway**: ClickBank
3. Enter your **Account ID** (your ClickBank account nickname)
4. Create an **Encryption Key** (see below for details)
5. Save the merchant configuration

### Understanding Encryption Keys

The encryption key is **not** an API key - it's a security key you create:

* **Purpose**: Encrypts data sent between ClickBank and ElasticFunnels
* **Security**: Prevents man-in-the-middle attacks on postback data
* **User-defined**: You create this key (can be any string)
* **Synchronization**: Must be identical in both ClickBank and ElasticFunnels

**Example**: `MySecretKey2024!` (use your own unique key)

<Note>
  For postback configuration, use the **Setup** modal available from the **Merchants** list. It provides the exact URL and parameters to copy into ClickBank and is kept up to date.
</Note>

## Step 2: Configure Domain-Merchant Assignment

### Assign Merchant to Domain

1. Go to **Settings** → **Domains** → **Edit Domain**
2. Select your ClickBank merchant from the dropdown
3. Save the domain configuration

This ensures all funnels on this domain use ClickBank for payments.

## Step 3: Set Up ClickBank Pitch Flow

### Create Pitch Flow in ClickBank

1. Log into your ClickBank account
2. Go to **Pitch Flows** section
3. Click **Create New Pitch Flow**
4. Add all product variants you plan to split test:
   * Different price points (3 bottles, 6 bottles, 12 bottles)
   * Different bonus packages
   * Different upsell combinations
5. Save and note the **Pitch Flow ID** (CBFID)

### Use Funnel Node URLs for Upsell/Decline Targets

Instead of pointing upsells to specific page slugs (e.g., `upsell-1`), use the URL from your funnel nodes:

1. Open your funnel in ElasticFunnels
2. For each step in your flow, click the **Purchase** or **Decline** node that leads to the next page
3. Click **Copy Node URL**
4. Paste this URL into the corresponding **Upsell** or **Decline** target in your ClickBank Pitch Flow

This decouples ClickBank from individual page URLs. You can later split test or swap the page shown at that node without changing the Pitch Flow or re‑approving it. See the "Copy Node URL" control on the nodes in your funnel builder for reference.

### Best Practices for Pitch Flow Setup

* **Include all variants**: Add every product combination you might test
* **Avoid re-approval delays**: Having all variants pre-approved saves time
* **Organize logically**: Group related products together
* **Document variants**: Keep track of which IDs correspond to which products

## Step 4: Configure Funnel Integration

### Set Funnel Pitch Flow ID

1. Go to **Funnels** → **Edit Funnel**
2. In the funnel settings, you'll see:
   * **ClickBank Pitch Flow ID**: Enter your CBFID
   * **ClickBank Template Code**: Enter if using custom templates
3. Save the funnel configuration

### Default Funnel Setup

* **Make funnel default**: Check this option if you want this funnel to handle all traffic to the domain without the `f=` parameter
* **URL access**: Visitors can access via `domain.com` or `domain.com?f=funnel_id`

## Postbacks

Use the **Setup** modal in the **Merchants** list for step-by-step, up-to-date postback instructions and your unique URL. After you configure ClickBank and trigger a test (or run a test purchase), the modal will automatically mark the connection as validated once the webhook is received.

## Advanced Configuration

### Multiple Product Testing

When split testing different products:

1. **Add all products** to the same pitch flow in ClickBank
2. **Use page events** to show different purchase buttons
3. **Pass product IDs** in the purchase links
4. **Track performance** of each variant

### Custom Purchase Links

Purchase links automatically use the funnel's CBFID:

* **Standard format**: `[BUY=product_code]`
* **With parameters**: `[BUY=product_code extra=campaign_data]`
* **No manual CBFID**: System automatically adds the funnel's pitch flow ID

### Upsell Configuration

1. **Create upsell nodes** in your funnel
2. **Connect to purchase nodes** for the main product
3. **Use funnel-level split testing** or page events for upsell variants
4. **Configure decline flows** for users who don't purchase upsells

### Subscription Upsells (Upgrade/Cancel)

If you sell recurring products, you can upgrade or cancel a customer's existing subscription mid-funnel using `[UPSELL_UPGRADE=old_sku, new_sku]` and `[UPSELL_CANCEL]` tags. This requires a **Developer API Key** (different from the encryption key) - see [Subscription Upsells](/products/subscription-upsells) for full setup instructions.

## Troubleshooting

### Common Issues

**Postback not working:**

* Verify encryption key matches in both systems
* Check postback URL is correctly entered in ClickBank
* Ensure merchant is properly assigned to domain

**Purchase links not working:**

* Verify funnel has correct CBFID
* Check that merchant is assigned to the domain
* Ensure products exist in ClickBank pitch flow

**Split testing not working:**

* Verify all product variants are in the pitch flow
* Check that page events are properly connected
* Ensure domain-merchant assignment is correct

### Testing Your Setup

1. **Use ClickBank's test mode** for initial testing
2. **Verify postback reception** in ElasticFunnels
3. **Test purchase flow** end-to-end
4. **Check conversion tracking** in both systems

## Security Best Practices

* **Keep encryption keys secure** - don't share them
* **Use strong, unique keys** - avoid simple passwords
* **Regularly rotate keys** - update periodically for security
* **Monitor postback logs** - watch for unusual activity
* **Test with small amounts** - verify everything works before full launch

<Warning>
  Ensure all your ClickBank pitch flow products are compliant with ClickBank's marketplace policies. Non-compliant products can result in account suspension.
</Warning>


# Digistore24
Source: https://docs.elasticfunnels.io/merchants/digistore24

Set up Digistore24 as a merchant, assign to a domain, and map products

This guide explains how to set up Digistore24 as a merchant. The overall flow matches the generic merchant setup; use this page for platform-specific notes.

## Step 1: Create Digistore24 Merchant

1. Go to **Settings** → **Merchants** → **Add Merchant**
2. Select **Gateway**: Digistore24
3. Enter your **Vendor ID** as provided by Digistore24
4. Save

## Step 2: Assign Merchant to Domain

1. Go to **Settings** → **Domains** → **Edit Domain**
2. Select your Digistore24 merchant
3. Save

## Step 3: Map Products

1. Go to **Settings** → **Products** → **Edit**
2. Open the **Merchant information** tab
3. Enter the **Digistore24 Product ID** for this product
4. Save

## Links and Funnels

Use `[BUY]`, `[UPSELL]`, and `[DOWNSELL]` tags so links auto-adapt per domain and merchant. Avoid pasting hardcoded Digistore24 checkout URLs.

* See [How to set up a new merchant](/guides/how-to-set-up-a-new-merchant)
* See [Buy Links](/products/buy-links)
* See [Advanced Purchase Links](/products/advanced-purchase-links)

## Postbacks

Use the **Setup** modal in the **Merchants** list for up-to-date postback instructions and your unique URL. After you configure the URLs in Digistore24 and send a test (or run a test purchase), the modal will automatically mark the connection as validated once the webhook is received.

## Troubleshooting

* Wrong gateway on checkout: Verify the domain is assigned to Digistore24
* Link not working: Ensure product mapping has the correct Digistore24 Product ID
* Missing affiliate data: Confirm affiliate sync settings and use adaptive tags


# High-Risk Merchants and Merchant Accounts
Source: https://docs.elasticfunnels.io/merchants/high-risk-and-merchant-accounts

What high risk actually means, why the gateway is not what approves you, and how to spread risk across multiple merchant accounts in ElasticFunnels

Most confusion about "high-risk payments" comes from mixing up two different things: the
**gateway** that moves the transaction and the **merchant account** that carries the risk.
They are separate, they are provided by different companies, and only one of them decides
whether you get approved.

## Gateway vs merchant account vs ElasticFunnels

| Layer | What it does | Who provides it | Does it decide if you are approved? |
| - | - | - | - |
| **Checkout / funnel** | Presents the offer, collects the payment, runs bumps and upsells, manages the subscription | ElasticFunnels | No |
| **Gateway** | Passes the transaction from the checkout to the acquirer, tokenises the card | NMI, Stripe, and similar | No |
| **Merchant account (MID)** | Holds the risk, receives the settlement, sets reserves and caps | An acquiring bank, usually via an ISO or payment facilitator | **Yes** |

<Note>
  **ElasticFunnels does not underwrite anyone and does not issue merchant accounts.** EF is
  the layer above the gateway. You bring the merchant accounts you already hold, and EF
  decides which one each transaction is sent to.
</Note>

This is why the question "is this gateway high risk?" has no useful answer. A gateway is
not high risk or low risk — it is a pipe. Two businesses on the same gateway can have
completely different experiences because they sit behind different acquirers.

## What "high risk" actually means

An acquirer classifies a merchant as high risk when the expected cost of the relationship
is higher than normal. The usual drivers:

* **Chargeback exposure** — supplements, continuity offers, coaching, trials
* **Delivery lag** — anything sold before it ships or before access is granted
* **Regulatory attention** — health claims, financial advice, CBD, adult
* **Recurring billing** — especially with free or discounted trials
* **Ticket size and velocity** — sudden volume spikes look like fraud
* **Cross-border settlement** — a merchant in one country, an acquirer in another

Being classified high risk does not mean you cannot process. It means higher rates, a
rolling reserve, volume caps, and closer monitoring — and it means a single merchant
account is a fragile place to put all of your revenue.

## Getting a merchant account

ElasticFunnels cannot get you approved, but the pattern that works is consistent:

1. **Apply through an ISO that knows your vertical.** A generic aggregator will approve you
   quickly and shut you down at the first chargeback spike. A specialist acquirer prices
   the risk in from the start.
2. **Expect to show the funnel.** Underwriters read the sales page, the checkout, the terms,
   the refund policy and the rebill disclosure. Vague continuity terms are the most common
   reason for decline.
3. **Have chargeback tooling in place before you apply.** Alert monitoring through
   [chargeback management](/integrations/chargeback-management) demonstrably reduces ratio,
   and underwriters ask about it.
4. **Plan for more than one MID.** Approvals take weeks. The time to add the second account
   is while the first one is healthy, not after it has been capped.

## Spreading risk across multiple MIDs

This is the part ElasticFunnels does, and it is the practical answer to being high risk.

Connect each merchant account as its own merchant in EF, then route across them:

* **Weighted routing** — send a defined share of volume to each MID so no single account
  carries the whole business or breaches its monthly cap
* **Cascade on soft declines** — when a charge fails for a recoverable reason
  (insufficient funds, AVS mismatch, issuer timeout), retry it on a different MID instead
  of losing the sale
* **Per-product and per-region routing** — keep a risky offer off the MID that carries your
  stable revenue
* **Per-MID approval reporting** — watch approval rate by account so you see degradation
  before the acquirer calls you

<Warning>
  Cascading is for **soft** declines only. A hard decline — stolen card, closed account, an
  issuer block — must not be retried on another MID. Retrying hard declines inflates your
  decline ratio and is exactly the behaviour that gets an account reviewed and shut down.
</Warning>

See [how to set up a new merchant](/guides/how-to-set-up-a-new-merchant) to connect each
account, and [subscriptions](/subscriptions/overview) for how rebills pick a MID.

## Keeping the accounts you have

Approval is the easy part. Staying approved is what decides whether the business survives.

* **Watch the chargeback ratio per MID, not in aggregate.** The acquirer measures your
  account, not your company. One bad offer on a shared MID takes down the good offers too.
* **Make the rebill obvious.** Clear terms at checkout, a renewal reminder before the
  charge, and an easy cancellation path prevent more chargebacks than any alert service.
  See [subscription emails and dunning](/subscriptions/emails-and-dunning).
* **Recover declines properly.** [Dunning](/subscriptions/emails-and-dunning) with sensible
  retry windows and [retention offers](/subscriptions/retention-offers) converts failed
  payments into revenue instead of cancellations.
* **Do not let one MID drift.** Falling approval rate on a single account usually means the
  acquirer has started filtering you, and it shows in EF's per-MID reporting well before
  it shows in your bank statement.

## Frequently asked

**Is a particular gateway high risk?**
No. Gateways do not underwrite. Your acquirer decides your classification. A gateway that
connects to many acquirers is useful precisely because you can change acquirer without
rebuilding your checkout.

**Can I create my own merchant account?**
You apply for one through an acquiring bank or an ISO — you cannot create one yourself, and
no software vendor can issue you one. What you can do is own the account directly rather
than processing under someone else's, which is what "bring your own MID" means in EF.

**Do I need a separate merchant account for Apple Pay and Google Pay?**
No. Wallets run through the merchant account you already have. See
[Apple Pay and Google Pay](/merchants/apple-pay-google-pay) — note the Customer Token Vault
requirement if you are billing wallet subscriptions.

**How many MIDs should I run?**
More than one, as soon as the revenue justifies the admin. Beyond that it depends on your
volume caps and how many distinct offers you run. The point at which a second MID pays for
itself is usually the first time the first one is capped or reviewed.


# JVZoo
Source: https://docs.elasticfunnels.io/merchants/jvzoo

Set up JVZoo as a merchant, including funnel ID, buy links, the tracking pixel, and affiliate attribution

This guide covers setting up JVZoo as a merchant to sell your products through JVZoo's hosted checkout, including the JVZoo funnel ID, buy links, the sales pixel, and affiliate attribution.

<Note>
  **This page is for vending your own products on JVZoo.** It is a different setup from the [JVZoo Affiliate S2S integration](/integrations/jvzoo#jvzoo-affiliate-s2s), which is for promoting *other* sellers' JVZoo products and earning commissions.

  They are independent — you can run both, and the two use different tracking parameters (`vtid` for your own sales, `tid` for affiliate commissions). Don't configure one expecting it to cover the other.
</Note>

## How JVZoo differs from other merchants

JVZoo is a **hosted checkout**. Your funnel owns the sales pages; JVZoo owns the cart, the payment, and the upsell sequence.

* There is **no checkout API** — buyers leave your page for JVZoo's checkout.
* **One-click upsells run inside JVZoo's funnel**, not ElasticFunnels'. The `jvzoo-checkout-state.js` script that JVZoo gives you belongs in the `<head>` of your upsell pages.
* The post-purchase thank-you page is configured **per product in the JVZoo product editor**, not passed as a redirect parameter.

## Prerequisites

* Active JVZoo seller account with an approved product funnel
* Your JVZoo **Account ID** (the vendor number, e.g. `117845`)
* Your product IDs from JVZoo (e.g. `448013` for the front end)
* Your JVZoo **funnel ID** — see Step 3

## Step 1: Create the JVZoo merchant

1. Go to **Settings** → **Merchants** → **Add Merchant**
2. Select **Gateway**: JVZoo
3. Enter your **Account ID** — your JVZoo vendor number. This becomes the first segment of every buy link.
4. Tick **Create tracking pixels** to have the JVZoo sales pixel added automatically (see [Tracking pixel](#tracking-pixel))
5. Save

## Step 2: Assign the merchant to a domain

1. Go to **Settings** → **Domains** → **Edit Domain**
2. Select your JVZoo merchant from the dropdown
3. Save

All funnels on this domain now build JVZoo buy links.

## Step 3: Get your JVZoo funnel ID

JVZoo buy buttons are generated **per funnel**, and the funnel ID is baked into the link:

```
https://www.jvzoo.com/b/117845/448013/99
                       ^vendor ^product ^funnel
```

To find it:

1. Log in to your JVZoo **Seller Dashboard**
2. Click the **⋯** menu next to your product → **Buy Buttons**
3. Select your **Funnel** from the dropdown at the top (not "No Funnel")
4. Read the last number off the generated button link — `99` in the example above

The same funnel ID appears on every product in that funnel, and in the tracking pixel URLs.

<Warning>
  If your product **is** in a JVZoo funnel, use the buy buttons from the funnel, not from the individual product. A link missing the funnel segment sends buyers through JVZoo's standalone-product flow, so your one-click upsells silently never run — the front-end sale still succeeds, which makes this fail quietly.
</Warning>

<Note>
  Selling a single product with no upsells? Choose **No Funnel** in JVZoo and leave **JVZoo Funnel ID** blank in ElasticFunnels. Buy links then have two segments instead of three, and everything else on this page works the same. See [Direct purchase links](#direct-purchase-links).
</Note>

## Step 4: Set the JVZoo Funnel ID in ElasticFunnels

1. Go to **Funnels** → **Edit Funnel**
2. In the **Domains** section, find the row for your JVZoo domain
3. Enter the funnel ID into **JVZoo Funnel ID**
4. Save

It lives on the domain row rather than the funnel itself, so one funnel served on two domains can point at two different JVZoo funnels. This mirrors how **ClickBank Pitch Flow ID** works.

## Product mapping

ElasticFunnels product codes are yours; JVZoo product IDs are numeric. Map them per product:

1. Go to **Products** → edit the product
2. Under **Merchant Product IDs**, set the **jvzoo** value to the JVZoo product ID (e.g. `448013`)

If no mapping exists, the product code is sent as-is — which only works if your ElasticFunnels code happens to be the JVZoo numeric ID.

## Buy links

Use the standard tag on your sales page:

```html theme={null}
<a href="[BUY=SMART_INCOME_MAIN_P37]" class="opt-in-submit">Buy Now</a>
```

With the merchant, mapping, and funnel ID configured, that expands to:

```
https://www.jvzoo.com/b/117845/448013/99?vtid=<click_code>&aff=<affiliate_id>
```

| Part | Source |
| - | - |
| `117845` | Merchant **Account ID** |
| `448013` | Product's **Merchant Product ID** for jvzoo |
| `99` | **JVZoo Funnel ID** on the funnel's domain row |
| `vtid` | ElasticFunnels click code — the vendor tracking ID, used to attribute the sale |
| `aff` | Affiliate ID, when the visit was affiliate-referred |

Upsell tags (`[UPSELL=...]`) build the same shape for your OTO products, carrying the same funnel ID and click code.

<Note>
  `vtid` is the **vendor** tracking parameter — your own sales. `tid` is the **affiliate** SubID, used when you promote someone else's product. ElasticFunnels never writes to `tid`, so an affiliate's own sub-tracking passes through untouched on affiliate-driven sales.
</Note>

## Direct purchase links

You don't have to use `[BUY=...]` tags — a hardcoded JVZoo link works too, and works with or without a funnel. **It must carry `vtid`**, or the sale arrives with no click attribution.

Use the `{click_id}` token and ElasticFunnels substitutes the visitor's click code when the page renders:

```html theme={null}
<!-- Product in a JVZoo funnel (99 is the funnel ID) -->
<a href="https://www.jvzoo.com/b/117845/448017/99?vtid={click_id}">Buy Now</a>

<!-- Standalone product, no funnel — two segments, trailing slash -->
<a href="https://www.jvzoo.com/b/117845/448017/?vtid={click_id}">Buy Now</a>
```

In a backend script, use the template-engine syntax instead:

```
https://www.jvzoo.com/b/117845/448017/99?vtid={{ click_id }}
```

`{click_id}` and `[click_id]` (and their URL-encoded forms) are the legacy page-HTML substitutions and are still supported; `{{ click_id }}` is the current template-engine syntax.

<Warning>
  The legacy `{click_id}` form is **case-sensitive** — `{CLICK_ID}` is not substituted and ships the literal text to JVZoo, which then posts back a tracking ID like `{CLICK_ID}` that matches no click. Those sales are flagged as a malformed click ID and cannot be attributed.
</Warning>

Prefer `[BUY=...]` tags where you can: they pick up the funnel ID, product mapping, and affiliate ID automatically, so a hardcoded link is one more place to update when any of those change.

## Tracking pixel

JVZoo requires a sales pixel on each sales page. Ticking **Create tracking pixels** when you add the merchant creates it for you:

```html theme={null}
<img src='https://i.jvzoo.com/{jvz_acc_id}/{product_code_first}/{jvz_funnel_id}' border="0" width="1" height="1" />
```

Nothing to fill in — all three values resolve per page at render time:

| Token | Resolves to |
| - | - |
| `{jvz_acc_id}` | The merchant's Account ID |
| `{product_code_first}` | JVZoo ID of the first buy button on the page |
| `{jvz_funnel_id}` | The funnel's JVZoo Funnel ID |
| `{product_codes_comma}` | Every product code on the page, deduped and comma-separated |

Because the product ID comes from the buy buttons, the same pixel works on your front end and every OTO page without editing.

## Affiliate attribution

JVZoo only tells you which affiliate sent a visitor if you turn it on, **per product**:

1. In the JVZoo product editor, find the **sales page URL** field
2. Set **Pass Affiliate ID to Sales Page** to **Yes**
3. Repeat for every product in the funnel

JVZoo then appends `?aid=<affiliate_id>` when it hands the visitor to your page. ElasticFunnels stores it in the session and puts it back on the buy link as `aff`, so JVZoo credits the sale.

<Warning>
  This setting is **off by default**. With it off, affiliate traffic arrives with no affiliate ID and those sales cannot be attributed — there is no way to recover the attribution afterwards.
</Warning>

## Postbacks

Sales, refunds, and chargebacks for products you vend come back over JVZIPN. Set this up under **JVZoo Vendor IPN** — see [JVZoo Vendor IPN](/integrations/jvzoo#jvzoo-vendor-ipn) for the secret key, IPN URL, and event mapping.

<Warning>
  Set up **JVZoo Vendor IPN**, not JVZoo Affiliate S2S. The affiliate one listens for commissions on other sellers' products and will never receive events for products you vend.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Upsells never run after the front-end sale">
    The buy link is missing its funnel segment, so JVZoo used the standalone-product flow. Check **JVZoo Funnel ID** is set on the funnel's domain row, and that you copied it from the funnel's buy buttons rather than the individual product's.
  </Accordion>

  <Accordion title="Buy link points at the wrong product">
    Check the product's **Merchant Product ID** for jvzoo. With no mapping, the ElasticFunnels product code is sent verbatim and JVZoo will not recognise it.
  </Accordion>

  <Accordion title="Affiliate sales recorded with no affiliate">
    **Pass Affiliate ID to Sales Page** is off for that product in JVZoo, so no `aid` ever reached your page. It must be enabled per product.
  </Accordion>

  <Accordion title="Sales recorded with no click attribution">
    The IPN arrived without a tracking ID matching an ElasticFunnels click code. Either the link was hardcoded without `?vtid={click_id}`, or the events are landing on the affiliate integration rather than JVZoo Vendor IPN. Inbound payloads are recorded under **Logs** → **Inbound Postbacks**.
  </Accordion>

  <Accordion title="Tracking ID arrives as the literal text {click_id}">
    The token wasn't substituted, so JVZoo received it verbatim. Check the capitalisation — `{click_id}` is case-sensitive — and that it is in the page's HTML rather than a tracking script or JS block.
  </Accordion>

  <Accordion title="Pixel renders with an empty product ID">
    `{product_code_first}` reads from the buy tags on the page. A page with no `[BUY=...]` or `[UPSELL=...]` tag has no product to report.
  </Accordion>
</AccordionGroup>


# PayPal
Source: https://docs.elasticfunnels.io/merchants/paypal

Offer PayPal as a payment option next to the card form on your checkout, with one-click upsells and subscriptions when your PayPal app can vault buyer wallets.

PayPal is a **payment option on your checkout**, shown as a tab next to the card form. The buyer picks PayPal, approves the payment on PayPal's own pages, and comes back to your funnel. Your card merchant (Stripe, NMI or Authorize.Net) still runs the card form on the same page.

<Info>
  PayPal is **never the main merchant of a domain or funnel**. A domain needs a card merchant, because the checkout's card form is built from it, and PayPal has no card form. The app does not let you pick PayPal (or Klarna) as a domain's merchant, a funnel's merchant, or the merchant a **Set Merchant** node switches to. You add PayPal to a checkout page instead, as shown below.
</Info>

***

## Before you start

You need:

1. A **PayPal Business** account.
2. An app in the [PayPal Developer Dashboard](https://developer.paypal.com/dashboard/applications), with its **Client ID** and **Secret**. Use a **Sandbox** app to test and a **Live** app to take real payments.
3. A card merchant on the domain the checkout runs on. See [How to set up a new merchant](/guides/how-to-set-up-a-new-merchant).

<Tip>
  If PayPal shows a "No-Code Checkout" page when you open your Live account, click **Manage API credentials** (or **Invite your developer**) to reach the Developer Dashboard.
</Tip>

***

## Step 1 - add the PayPal merchant

1. Go to **Merchants** → **Add Merchant** and choose **PayPal**.
2. Paste the **Client ID** and **Secret**. Sandbox and Live credentials have their own fields, and the **Mode** toggle decides which pair is used.
3. Save.

When you save, ElasticFunnels:

* **Creates the webhook on your PayPal app** for captures, refunds, voids and disputes, so refunds and chargebacks reach your reports without any setup on your side.
* **Checks whether your PayPal app can vault buyer wallets.** Vaulting is what makes one-click upsells and subscriptions possible (see below). The check places a \$1.00 test order that the buyer never approves, so nothing is charged.

***

## Step 2 - add the PayPal tab to your checkout page

Add `data-paypal` to the card panel, with your PayPal merchant's **ID** (shown on the Merchants list):

```html theme={null}
<checkout-cc-panel data-accepted-cards="visa,mastercard,amex,discover" data-paypal="171"></checkout-cc-panel>
<div data-checkout-message></div>

<button type="button" data-checkout-submit>Complete my order</button>
```

The panel now renders as two tabs: **Credit Card** (from the domain's merchant) and **PayPal**. The same **Complete my order** button submits either one. Nothing else on the page changes: the order summary, bumps, totals and the customer fields all work the same way. See [How to design a checkout page](/guides/how-to-design-a-checkout-page) for the full page.

In the **page builder**, select the **Credit Card Form** block and pick the merchant under **PayPal Options → PayPal Merchant**.

<Note>
  `data-paypal` is set per page on purpose. A checkout only offers PayPal where you add it, so you can keep PayPal off a page (for example a subscription offer you only want on cards) without touching the merchant.
</Note>

<Warning>
  `data-paypal` only counts when the ID belongs to a **PayPal** merchant in the same brand. A deleted merchant or a typo in the ID hides the PayPal tab, and the card form keeps working.
</Warning>

***

## What the buyer sees

1. The buyer fills in their email and name, picks the **PayPal** tab and clicks the button.
2. They are sent to PayPal, log in and approve the payment. The amount PayPal shows includes bumps, tax and shipping.
3. PayPal sends them back to your funnel, the payment is captured, and they continue to the next step (an upsell or the thank-you page), exactly as after a card payment.

If the buyer cancels on PayPal, they return to the checkout and can pay with a card instead. If PayPal cannot start the payment, the buyer stays on the checkout with a message to pay by card or try again; the cause is recorded for your support team.

***

## One-click upsells and subscriptions (vaulting)

When your PayPal app can **vault** buyer wallets, the first PayPal payment also saves the buyer's PayPal wallet for later charges that the buyer agreed to:

| | With vaulting | Without vaulting |
| - | - | - |
| **Upsells** after a PayPal checkout | Charged to the saved PayPal wallet in one click, without leaving the funnel | The buyer is sent to PayPal to approve each upsell |
| **Subscriptions** paid with PayPal | Renewals are charged automatically to the saved wallet | The first payment works, but renewals cannot be charged |

If a one-click upsell charge fails, the buyer is sent to PayPal to approve it instead of seeing a decline.

### Turning vaulting on

Vaulting is a feature PayPal enables on your app. ElasticFunnels checks it every time you save the merchant. If it is off:

* Checkout still works. Payments complete normally without vaulting.
* One-click upsells fall back to the PayPal approval page, and subscription renewals cannot be charged until vaulting is on.

To enable it, open your app in the PayPal Developer Dashboard and turn on **Save payment methods** (PayPal's vault feature) under the app's features. On Live accounts PayPal may need to approve it. Then save the PayPal merchant again so the check runs again.

***

## Tracking numbers are sent to PayPal

When an order paid through a PayPal merchant gets a tracking number, ElasticFunnels adds it to the PayPal transaction. PayPal uses it to settle "item not received" disputes. The tracking number can come from:

* a fulfillment integration ([ShipOffers or Jetpack](/integrations/fulfillment)), or
* your Shopify store, when the order was sent there with [Shopify Order Sync](/integrations/shopify-order-sync#tracking-back-from-shopify) and shipped from Shopify.

There is nothing to set up. Each tracking number is sent once per payment. A carrier PayPal does not recognise is sent as "Other". If PayPal rejects the call, the order itself is not affected.

***

## Testing with the PayPal sandbox

1. Create a **Sandbox** app in the Developer Dashboard and copy its Client ID and Secret into the sandbox fields of the PayPal merchant.
2. Set **Mode** to **Sandbox**, or keep Live and use the merchant's test key: see [Test mode](/merchants/test-mode).
3. Open your checkout, choose PayPal, and log in with a **sandbox personal account** from **Testing Tools → Sandbox Accounts** in the Developer Dashboard.

Sandbox payments are recorded as **test** orders.

***

## Klarna

Klarna works the same way: add `data-klarna="<merchant id>"` to the card panel to show a Klarna tab, and like PayPal it cannot be a domain's or funnel's main merchant.

***

## Related

* [How to design a checkout page](/guides/how-to-design-a-checkout-page)
* [Checkout functionality reference](/checkouts/checkout-functionality-reference) - every `<checkout-cc-panel>` attribute
* [Test mode](/merchants/test-mode)
* [Apple Pay and Google Pay](/merchants/apple-pay-google-pay)
* [Postback URLs](/merchants/postback-urls) - PayPal sales, refunds and disputes fire the same payload as card sales


# Postback URLs
Source: https://docs.elasticfunnels.io/merchants/postback-urls

Send a standardized JSON payload to your own URL whenever a merchant lifecycle event happens - independent of the underlying payment gateway.

ElasticFunnels can fire an outbound HTTP POST to a URL you control whenever a merchant event happens - a purchase, a refund, a subscription renewal, a chargeback, and so on. The payload is **the same regardless of which gateway** (Stripe, NMI, PayPal, ClickBank, BuyGoods, Digistore24, Klarna, Shop Pay, Shopify Checkout) actually processed the transaction, so you only have to integrate once.

This is intentionally simpler than building a full automation graph in the **Automations** module. Use postback URLs when you just need to forward a clean, predictable JSON event to your own backend, your data warehouse, an internal CRM, or a third-party partner.

<Note>
  Postback URLs do not replace the [Automations](/integrations/automations) module - they are complementary. Automations are great for branching logic, retries with conditions, and connecting many third-party services. Postback URLs are great for "fire-and-forget" event forwarding.
</Note>

## Where to configure

In your brand:

1. Go to **Settings** → **Merchants** → pick a merchant → **Edit**.
2. Open the **Postback URLs** tab.
3. For each event you care about, set:
   * **Postback URL** - `https://your-app.example.com/webhooks/elasticfunnels`
   * **Authorization** - a token we send as `Authorization: Bearer <token>`, so you can gate the endpoint at a reverse proxy before it ever reaches your app. Use **Generate token** for a random one, or paste your own. Leave it blank and we generate one for you when you save - the field is never actually empty, so expect the header on every request.
   * **Enabled** - must be checked for the URL to fire.
4. Use the **Send test** button next to each URL to deliver a sample payload right away.
5. The **Recent deliveries** section shows status, HTTP code, attempts, the exact payload that was sent, and lets you retry failed deliveries manually.

The same tab also exposes the **Signing secret** that we use to sign every outbound request. Reveal it once when you wire up your verifier, and you can rotate it at any time.

## Supported events

| Event key | Fires when |
| - | - |
| `purchase` | A new approved purchase / order is recorded |
| `refund` | A refund (full or partial) is recorded |
| `chargeback` | A chargeback is recorded |
| `subscription_renewal` | A recurring charge succeeds |
| `subscription_renewal_failed` | A recurring charge fails (decline, processor error, etc.) |
| `subscription_cancel` | A subscription is cancelled (by the customer, the merchant, or dunning) |
| `subscription_change` | A subscription is upgraded / downgraded / paused |
| `abandon` | Cart abandonment is recorded |
| `failed_payment` | An initial payment attempt fails (not a renewal - see above) |
| `shipped` | A tracking number is assigned to an order for the first time |

You can configure a different URL per event, or use the same URL for every event - your handler can branch on the `event` field and on the `X-EF-Event` header.

## Request format

Every request looks like this:

```http theme={null}
POST /your/handler HTTP/1.1
Host: your-app.example.com
Content-Type: application/json
User-Agent: ElasticFunnels-Postback/1.0
X-EF-Event: purchase
X-EF-Delivery-Id: 01HXYZ...
X-EF-Timestamp: 1755555555
X-EF-Signature: sha256=8c0e...
X-EF-Brand-Id: 42
X-EF-Merchant-Id: 17
Authorization: Bearer <the token on that URL's row>
```

| Header | Purpose |
| - | - |
| `X-EF-Event` | The event name (same as `event` in the body). |
| `X-EF-Delivery-Id` | Unique ID for this delivery attempt (use it for idempotency on your side). |
| `X-EF-Timestamp` | Unix timestamp of when the signature was computed. |
| `X-EF-Signature` | `sha256=` + HMAC-SHA256 of `<timestamp>.<raw_body>` using your merchant's signing secret. |
| `X-EF-Brand-Id` | The brand the merchant belongs to. |
| `X-EF-Merchant-Id` | The merchant the postback came from. |
| `Authorization` | Bearer token for that URL's row. Snapshotted when the delivery is queued, so retries keep sending the token that was in effect at the time - rotating it will not change an already-queued delivery. |

### Verifying the signature

Reject any request whose recomputed signature does not match `X-EF-Signature`. Always compare with a constant-time function (`hash_equals` in PHP, `crypto.timingSafeEqual` in Node, etc.). It is also a good idea to reject requests whose `X-EF-Timestamp` is more than a few minutes in the past or future.

<CodeGroup>
  ```php PHP theme={null}
  $secret    = getenv('EF_POSTBACK_SECRET');
  $body      = file_get_contents('php://input');
  $timestamp = $_SERVER['HTTP_X_EF_TIMESTAMP'] ?? '';
  $signature = $_SERVER['HTTP_X_EF_SIGNATURE'] ?? '';

  $expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);

  if (! hash_equals($expected, $signature)) {
      http_response_code(401);
      exit('invalid signature');
  }

  if (abs(time() - (int) $timestamp) > 300) {
      http_response_code(401);
      exit('timestamp too old');
  }

  $payload = json_decode($body, true);
  ```

  ```js Node.js theme={null}
  import crypto from 'crypto';

  export function verify(req, rawBody, secret) {
    const timestamp = req.headers['x-ef-timestamp'];
    const signature = req.headers['x-ef-signature'];

    const expected =
      'sha256=' +
      crypto
        .createHmac('sha256', secret)
        .update(`${timestamp}.${rawBody}`)
        .digest('hex');

    const ok =
      signature &&
      expected.length === signature.length &&
      crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

    const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;

    return ok && fresh;
  }
  ```

  ```python Python theme={null}
  import hmac, hashlib, time

  def verify(secret: str, raw_body: bytes, headers: dict) -> bool:
      timestamp = headers.get('x-ef-timestamp', '')
      signature = headers.get('x-ef-signature', '')

      expected = 'sha256=' + hmac.new(
          secret.encode(),
          f"{timestamp}.".encode() + raw_body,
          hashlib.sha256,
      ).hexdigest()

      if not hmac.compare_digest(expected, signature):
          return False

      return abs(int(time.time()) - int(timestamp)) < 300
  ```
</CodeGroup>

### Response handling

* Return any `2xx` status to acknowledge the delivery. The body is ignored (but stored in the deliveries log for debugging - keep it under a few KB).
* Any non-2xx response, timeout, or connection error counts as a failure.
* Failed deliveries are retried automatically with exponential backoff: `1m → 5m → 30m → 2h → 12h` (up to 5 attempts). After the final failure the delivery is marked **dead** and stops retrying. You can re-queue it manually from the Postback URLs tab.
* Each delivery has a unique `X-EF-Delivery-Id`. Use it to dedupe on your end.

## Standardized payload

All events share the same envelope. Fields that don't apply to a given event are present but `null`. The full schema:

```json theme={null}
{
  "event": "purchase",
  "event_id": "ef_evt_01HXYZ...",
  "occurred_at": "2026-04-18T13:45:21+00:00",
  "test": false,

  "brand_id": 42,
  "merchant": {
    "id": 17,
    "gateway": "stripe",
    "name": "Acme Stripe (Live)"
  },

  "order": {
    "order_id": "OFF-1234",
    "public_order_id": "EF-1234",
    "transaction_id": "ch_3PXyz...",
    "conversion_code": "abc123def456",
    "original_conversion_code": null,
    "status": "approved",
    "is_subscription": true,
    "subscription": {
      "cycle_number": 2,
      "status": "active",
      "next_charge_at": "2026-05-18T13:45:21+00:00",
      "retry_count": 0,
      "max_retries": 6,
      "cancel_reason": null,
      "decline_reason": null,
      "recovered_from_dunning": null
    }
  },

  "customer": {
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "name": "Jane Doe",
    "phone": "+15555550100",
    "country": "US",
    "address": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "ip": "203.0.113.42"
  },

  "billing": {
    "address": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US"
  },

  "shipping": {
    "address": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US",
    "tracking_number": null,
    "tracking_url": null,
    "carrier": null,
    "shipping_method": null
  },

  "amounts": {
    "currency": "USD",
    "total": 49.0,
    "subtotal": 45.0,
    "taxes": 4.0,
    "shipping": 0.0,
    "discount": 0.0,
    "cogs": 12.0,
    "merchant_commission": 0.0,
    "affiliate_commission": 0.0,
    "refunded_total": 0.0
  },

  "products": [
    {
      "code": "SKU-MAIN-1",
      "sku": "SKU-MAIN-1",
      "product_id": 901,
      "name": "Acme Widget",
      "quantity": 1,
      "price": 45.0,
      "unit_price": 45.0,
      "total": 45.0,
      "currency": "USD",
      "type": "main",
      "is_bonus": false,
      "image_url": null,
      "tracking_number": null,
      "tracking_url": null,
      "carrier": null
    }
  ],

  "tracking": {
    "click_code": "ck_abc123",
    "session_id": "sess_xyz",
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "spring",
    "utm_term": null,
    "utm_content": null,
    "gclid": null,
    "fbclid": null,
    "subid": null,
    "subid2": null,
    "subid3": null,
    "subid4": null,
    "subid5": null,
    "vtid": null
  },

  "affiliate": {
    "id": null,
    "source": null,
    "merchant_affiliate_id": null,
    "merchant_affiliate_name": null
  },

  "funnel": {
    "funnel_id": 7,
    "page_id": 21,
    "domain_id": 3
  },

  "coupon": {
    "code": null,
    "discount": 0.0
  },

  "meta": {
    "payment_method": "card",
    "payment_status": "completed",
    "last4": "4242",
    "gateway": "stripe"
  }
}
```

### Passing your own tracking values

Six fields in `tracking` are yours to populate - `vtid` and `subid` through `subid5`. Put any of them on the landing URL or on the buy link as a query parameter and we capture, store, and echo the value back on every postback for that order:

```
https://yourdomain.com/lander?vtid=YOUR_KEY
https://yourdomain.com/b?p=product_1&vtid=YOUR_KEY
```

* **`vtid`** - "vendor tracking ID". A single general-purpose slot, independent of gateway and of any affiliate network. Best choice for a third-party tracker or session key that you need reflected back. Keep values under **512 characters**: the postback echoes the value in full, but the click record truncates at 512, so a longer value will not match between the two when you reconcile. This matters most for base64/encoded composite keys, which get long quickly.
* **`subid` .. `subid5`** - five slots conventionally used for affiliate-network sub-tracking (RedTrack, Voluum, and similar).

All six are also filterable and exportable from the **Conversions** report, so you can reconcile against the postbacks you received.

<Note>
  Upsell and rebill conversions inherit these values from the original purchase, so a subscription's renewals carry the same `vtid` as the sale that created it.
</Note>

### Event-specific notes

* **`refund` / `chargeback`** - `amounts.total` is **negative** for the refunded portion, and `order.original_conversion_code` references the original purchase row.
* **`subscription_renewal_failed`** - `order.subscription.retry_count` and `order.subscription.next_charge_at` reflect the dunning schedule, and `meta.payment_status` will typically be `failed` with a populated `order.subscription.decline_reason`.
* **`subscription_cancel`** - `order.subscription.status` is `cancelled` and `order.subscription.cancel_reason` is filled when available.
* **`shipped`** - fires the **first time** a tracking number is set on an order. `shipping.tracking_number`, `shipping.tracking_url`, and `shipping.carrier` are populated. We dedupe per order so you only get one `shipped` event.
* **`abandon`** - `order.status` is `abandoned` and `customer` may be partially populated depending on how far the visitor got in checkout.
* **`test`** - Postbacks fired from the **Send test** button or originating from a sandbox merchant set `test: true`. Use it to gate side effects in your handler.

## Example: minimal Express.js handler

```js theme={null}
import express from 'express';
import crypto from 'crypto';

const app = express();
const SECRET = process.env.EF_POSTBACK_SECRET;

app.post(
  '/webhooks/elasticfunnels',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const raw = req.body.toString('utf8');
    const ts = req.header('x-ef-timestamp') || '';
    const sig = req.header('x-ef-signature') || '';

    const expected =
      'sha256=' + crypto.createHmac('sha256', SECRET).update(`${ts}.${raw}`).digest('hex');

    const valid =
      sig.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig)) &&
      Math.abs(Date.now() / 1000 - Number(ts)) < 300;

    if (!valid) return res.status(401).end();

    const evt = JSON.parse(raw);
    console.log(`[${evt.event}] order=${evt.order.public_order_id} total=${evt.amounts.total}`);

    res.status(200).end();
  }
);

app.listen(3000);
```

## Operational details

* Deliveries are processed asynchronously so they do not block the gateway request that triggered them.
* Failed deliveries are retried automatically after the configured backoff window has elapsed.
* The Postback URLs tab shows recent deliveries, including the URL, payload, headers, response body, attempts, and final status.
* The signing secret is stored encrypted at rest. Rotating it invalidates all previous signatures immediately - only do it if you can update your verifier in lockstep.


# Shop Pay
Source: https://docs.elasticfunnels.io/merchants/shop-pay

Set up Shop Pay (Shopify draft order checkout) as a merchant, assign to a domain, and map products to Shopify variant IDs

This guide explains how to set up Shop Pay as a merchant. When a visitor clicks a buy link, ElasticFunnels creates a draft order in Shopify and sends them to Shopify checkout. Returning customers can use Shop Pay one-click. The overall flow matches the generic merchant setup; use this page for Shop Pay-specific notes.

<Note>
  **Shop Pay** uses Shopify's Draft Order API and supports bumps (multiple line items). For a simple cart redirect to your Shopify store, see [Shopify Checkout](/merchants/shopify-checkout) instead.
</Note>

## Prerequisites

* A Shopify store (same connection as Order Sync). One store per brand
* Admin access to your Shopify store and to ElasticFunnels
* The ElasticFunnels team sets up the Shopify app for your brand and sends you the install link (see [Shopify Order Sync](/integrations/shopify-order-sync#set-up))

## Step 1: Connect Shopify and enable Shop Pay

Shop Pay requires your Shopify store to be connected so ElasticFunnels can create draft orders.

1. Go to **Integrations** → **Operations**, find **Shopify**, and connect your store (see [Shopify Order Sync](/integrations/shopify-order-sync) for the full flow)
2. When connecting (or in the integration settings), enable **Shop Pay** so the integration can create draft orders

When you enable **Shop Pay**, a **Shop Pay** merchant is created automatically and linked to the integration. You do not need to create the merchant manually.

## Step 2: Assign merchant to domain

1. Go to **Settings** → **Domains** → **Edit Domain**
2. Select your **Shop Pay** merchant (created in Step 1)
3. Save

## Step 3: Map products

Each product must be linked to a **Shopify variant ID** (a numeric ID from your Shopify store).

<Note>
  If **Enable Shop Pay Merchant** was on when you connected the store, ElasticFunnels creates your products in Shopify (one variant each, inventory not tracked) and fills in the variant ID for you; later edits to a product are sent to Shopify too. With **Sync orders to Shopify** on, the **Sync products** button on the Shopify card does the same for products not in Shopify yet. Enter a variant ID by hand when the field is still empty, or to use a product that already exists in your Shopify store.
</Note>

To enter it by hand:

1. Go to **Settings** → **Products** → **Edit** the product
2. Open the **Merchant information** tab
3. Find the row for your **Shop Pay** merchant
4. Enter the **Shopify variant ID** (numbers only) for this product
5. Save

### How to find your Shopify variant ID

* **Products with variants:** In Shopify Admin go to **Products** → open the product → **Variants** → click the variant. The URL in your browser will look like `.../variants/36485954240671`. The number after `/variants/` is the variant ID.
* **Products with a single variant:** Open the product in Shopify Admin, add `.json` to the end of the URL, and press Enter. In the JSON, look at the `variants` array and use the `id` of the first (or only) variant.

<Info>
  Every Shopify product has at least one variant. Use the variant ID, not the product ID.
</Info>

## How it works

When a visitor clicks a buy link on your funnel:

* A **draft order** is created in your Shopify store with the selected product (and any bump products)
* The customer is redirected to Shopify checkout to complete payment
* Returning customers can use **Shop Pay** one-click checkout when available
* Bumps are supported. Multiple line items can be added to the same draft order
* When the order is paid, Shopify notifies ElasticFunnels and the sale is recorded with its click ID, products and bonuses. Refunds are linked to the sale
* There are no one-click upsells: payment happens on Shopify, so each purchase goes through Shopify checkout
* These orders already exist in Shopify, so [Shopify Order Sync](/integrations/shopify-order-sync) does not send them again

There is no “decline” link; if the customer does not complete checkout, they simply leave. Use the **Setup** modal in the **Merchants** list for postback configuration and validation.

## Links and Funnels

Use `[BUY]`, `[UPSELL]`, and `[DOWNSELL]` tags so links auto-adapt per domain and merchant. Avoid pasting hardcoded Shopify or Shop Pay URLs.

* See [How to set up a new merchant](/guides/how-to-set-up-a-new-merchant)
* See [Buy Links](/products/buy-links)
* See [Advanced Purchase Links](/products/advanced-purchase-links)

## Postbacks

Use the **Setup** modal in the **Merchants** list for step-by-step postback instructions and your unique URL. After you configure the postback and trigger a test (or complete a test purchase), the modal will automatically mark the connection as validated once the webhook is received.

## Troubleshooting

* **"Product missing Shopify product ID"** or **"missing Shopify product ID"**: In the product's **Merchant information** tab, enter the Shopify variant ID for the Shop Pay merchant. Use the steps above to find the variant ID in Shopify Admin.
* **"Shop Pay gateway requires a Shopify integration"** or **"requires a Shopify store domain"**: Connect Shopify under **Integrations** → **Operations** and turn on **Enable Shop Pay Merchant** on the Shopify card, so the Shop Pay merchant is created and linked to your store.
* **Wrong gateway on checkout**: Verify the domain is assigned to your Shop Pay merchant.
* **Link not working**: Confirm the product has the correct Shopify variant ID in **Merchant information** for this merchant.


# Shopify Checkout
Source: https://docs.elasticfunnels.io/merchants/shopify-checkout

Set up Shopify Checkout (cart redirect) as a merchant, assign to a domain, and map products to Shopify variant IDs

This guide explains how to set up Shopify Checkout as a merchant. When a visitor clicks a buy link, they are redirected to your Shopify store's cart and then to Shopify's native checkout. The overall flow matches the generic merchant setup; use this page for Shopify Checkout-specific notes.

<Note>
  **Shopify Checkout** sends customers to your Shopify cart (cart redirect). For a draft-order checkout with Shop Pay for returning customers and bump support, see [Shop Pay](/merchants/shop-pay) instead.
</Note>

## Prerequisites

* A Shopify store with products (and variants, if you use multiple variants)
* Admin access to your Shopify store and to ElasticFunnels
* The ElasticFunnels team sets up the Shopify app for your brand and sends you the install link (see [Shopify Order Sync](/integrations/shopify-order-sync#set-up)). One store per brand

## Step 1: Connect Shopify and enable Shopify Checkouts

1. Go to **Integrations** → **Operations**, find **Shopify**, and connect your store (see [Shopify Order Sync](/integrations/shopify-order-sync) for the full flow)
2. Enable **Shopify Checkouts** so postbacks are received for orders created, updated, or deleted in your store

When you enable **Shopify Checkouts**, a **Shopify Checkouts** merchant is created automatically and linked to the integration. You do not need to create the merchant manually.

## Step 2: Assign merchant to domain

1. Go to **Settings** → **Domains** → **Edit Domain**
2. Select your **Shopify Checkouts** merchant (created in Step 1)
3. Save

## Step 3: Map products

Each product must be linked to a **Shopify variant ID** (a numeric ID from your Shopify store).

1. Go to **Settings** → **Products** → **Edit** the product
2. Open the **Merchant information** tab
3. Find the row for your **Shopify Checkouts** merchant
4. Enter the **Shopify variant ID** (numbers only) for this product
5. Save

### How to find your Shopify variant ID

* **Products with variants:** In Shopify Admin go to **Products** → open the product → **Variants** → click the variant. The URL in your browser will look like `.../variants/36485954240671`. The number after `/variants/` is the variant ID.
* **Products with a single variant:** Open the product in Shopify Admin, add `.json` to the end of the URL, and press Enter. In the JSON, look at the `variants` array and use the `id` of the first (or only) variant.

<Info>
  Every Shopify product has at least one variant. Use the variant ID, not the product ID.
</Info>

## How it works

In your funnel, buy links use your **product code** (the same code you use for other gateways). When a visitor clicks add to cart or a buy link, we look up the **Shopify variant ID** you mapped for that product in **Merchant information** and redirect them to your Shopify store.

* They are redirected to your Shopify store at `/cart/{variantId}:1` (one unit of that variant)
* The click ID is passed as a cart attribute so conversions can be tracked
* From the cart they proceed to Shopify's native checkout

Shopify Checkout does **not** support one-click upsells. It is a simple cart redirect and payment happens on Shopify. [Shop Pay](/merchants/shop-pay) adds bump support but has no one-click upsells either.

Orders placed this way already exist in Shopify, so [Shopify Order Sync](/integrations/shopify-order-sync) does not send them again.

## Links and Funnels

Use `[BUY]`, `[UPSELL]`, and `[DOWNSELL]` tags so links auto-adapt per domain and merchant. Avoid pasting hardcoded Shopify cart URLs.

* See [How to set up a new merchant](/guides/how-to-set-up-a-new-merchant)
* See [Buy Links](/products/buy-links)
* See [Advanced Purchase Links](/products/advanced-purchase-links)

## Postbacks

Orders from your Shopify store (including those that started from a funnel cart link) are reported via the Shopify integration. Ensure **Shopify Checkouts** is enabled in your **Shopify** integration (**Integrations** → **Operations**) so postbacks are received for orders created, updated, or deleted in the store.

## Troubleshooting

* **"Product missing Shopify variant ID"**: In the product's **Merchant information** tab, enter the Shopify variant ID for the Shopify Checkout merchant. Use the steps above to find the variant ID in Shopify Admin.
* **"Shopify Checkout requires a linked Shopify integration"**: Connect Shopify under **Integrations** → **Operations** and ensure the merchant or domain is linked to that integration so the store domain is available.
* **Wrong gateway on checkout**: Verify the domain is assigned to your Shopify Checkout merchant.
* **Link not working**: Confirm the product has the correct Shopify variant ID in **Merchant information** for this merchant.


# Cart
Source: https://docs.elasticfunnels.io/pages/cart

Add a cart to your page so visitors see their items, quantities, and total—and can change quantity or go to checkout

The cart shows what the visitor has added to their order: each item, quantity, price, and the total. It updates live when they add items or change quantities, without reloading the page.

## Adding a cart to your page

In the page builder you can add:

* **Cart** – A single cart block (list of items + total + checkout).
* **Cart Dropdown** – A "Cart" trigger (e.g. with item count) that opens a dropdown panel with the same cart inside. Handy in headers or sidebars.

Both use the same cart data; only the placement and layout differ.

### Where to find them

1. Open the **Elements** or **Blocks** panel.
2. In the **Cart** category, choose **Cart** or **Cart Dropdown**.
3. Drag the block onto your page where you want it (e.g. below the fold for Cart, in the top bar for Cart Dropdown).

The default Cart block already includes:

* A row per item (name, quantity controls, unit price, line total).
* A footer with **Total** and a **Checkout** link.

You can keep this layout or edit it (e.g. change labels, order of fields, or styling).

## What visitors see

* **Item name** – From your product/offer (e.g. "1 Bottle").
* **Item image** – Product thumbnail (if the product has one).
* **Quantity** – Current quantity with **−** and **+** to decrease or increase.
* **Unit price** – Price per unit (e.g. "\$69.00").
* **Line total** – Price × quantity for that item (e.g. "\$552.00").
* **Cart total** – Sum of all line totals, shown in the footer (e.g. "Total: \$552.00").
* **Checkout** – Link to continue to checkout.

All of this updates automatically when they add to cart or change quantity.

## Customizing the cart layout

The cart is built from a **template**: you can change text, order of fields, and styling in the builder.

### Cart-level variables

These apply to the cart as a whole:

| Variable | Description |
| - | - |
| **`[[ efCart.total ]]`** | Grand total of all items (formatted, e.g. "\$138.00") |
| **`[[ efCart.subtotal ]]`** | Same as `efCart.total` (alias) |
| **`[[ efCart.count ]]`** | Total quantity across all items (sum of quantities, e.g. "2") — use for an item count badge |
| **`[[ efCart.item_count ]]`** | Number of distinct product lines in the cart |
| **`[[ efCart.discount_total ]]`** | Total savings across all items (formatted) |
| **`[[ efCart.currency ]]`** | Currency code (e.g. "USD") |

### Per-item row variables

Inside a `template-foreach` loop, each item exposes:

| Variable | Description |
| - | - |
| **`[[ item.name ]]`** | Item name |
| **`[[ item.image ]]`** | Product image URL |
| **`[[ item.code ]]`** | Product code (needed for quantity controls) |
| **`[[ item.quantity ]]`** | Current quantity |
| **`[[ item.price ]]`** | Unit price (formatted, e.g. "\$69.00") — do not apply `formatPrice` |
| **`[[ item.total ]]`** | Line total (formatted, e.g. "\$138.00") — do not apply `formatPrice` |
| **`[[ item.retail_price ]]`** | Original/retail price (formatted) — shown when there is a discount |
| **`[[ item.discount_total ]]`** | Per-line savings (formatted) |
| **`[[ item.currency ]]`** | Currency code for this item |
| **`[[ item.is_subscription ]]`** | `true` when this is a subscription product |
| **`[[ item.subscription ]]`** | Subscription billing details — `null` for one-time products (see [Subscription info](#subscription-info)) |
| **`[[ item.bonuses ]]`** | Free bonus products linked to this item (see [Bonus products](#bonus-products)) |
| **`[[ item.courses ]]`** | Courses linked to this product (see [Courses](#courses)) |

<Info>
  **`item.price`** and **`item.total`** are already formatted. Use them as-is. See [Frontend Template Engine — Cart](/frontend-template-engine/cart) for the full data attributes reference.

  `bonuses`, `courses`, `is_subscription`, and `subscription` are populated after a brief async fetch when the cart loads. They are always present so templates never error on an undefined value.
</Info>

### Subscription info

When `item.is_subscription` is `true`, `item.subscription` contains:

| Property | Description |
| - | - |
| **`frequency`** | Billing interval number (e.g. `3`) |
| **`frequency_unit`** | Unit: `"day"`, `"week"`, `"month"`, or `"year"` |
| **`trial_days`** | Free trial days (`0` = no trial) |
| **`first_charge_free`** | `true` when the first cycle is free |

```html theme={null}
<template-if data-condition="item.is_subscription">
  <span>Every [[ item.subscription.frequency ]] [[ item.subscription.frequency_unit ]]</span>
</template-if>
```

The same fields are available on the checkout scope for single-product checkout pages:
`[[ checkout.is_subscription ]]` and `[[ checkout.subscription.frequency ]]` etc.

### Bonus products

Products can have **bonus items** attached — free gifts or complementary products included with the purchase (configured in the product catalog). They are available as `item.bonuses` — always an array, empty when no bonuses are configured.

Each bonus has: `code`, `name`, `image`, `price`, `retail_price`, `original_price`, `currency`.

```html theme={null}
<template-foreach data-each="item in cartItems">
  <div class="cart-line">
    <img src="[[ item.image ]]" alt="[[ item.name ]]" />
    <span>[[ item.name ]]</span>
    <span>[[ item.price ]]</span>
    <template-foreach data-each="bonus in item.bonuses">
      <div class="cart-bonus-row">
        <img src="[[ bonus.image ]]" alt="[[ bonus.name ]]" />
        <span>[[ bonus.name ]]</span>
        <span>FREE <s>[[ bonus.retail_price ]]</s></span>
      </div>
    </template-foreach>
  </div>
</template-foreach>
```

### Courses

When a product has linked courses (e.g. digital bonuses delivered via the course platform), they are available as `item.courses` — always an array, empty when no courses are linked.

Each course has: `id`, `title`, `slug`, `description`, `cover`, `instructor_name`, `status`.

```html theme={null}
<template-foreach data-each="course in item.courses">
  <div class="cart-course-row">
    <img src="[[ course.cover ]]" alt="[[ course.title ]]" />
    <span>[[ course.title ]]</span>
  </div>
</template-foreach>
```

Both the `[[ ]]` placeholder syntax and the **`ef-text`** binding attribute are supported. They are equivalent — use whichever fits your template:

```html theme={null}
<!-- placeholder syntax -->
<span>[[ efCart.total ]]</span>
<span>[[ item.price ]]</span>

<!-- ef-text binding (fallback content shown in builder, replaced at runtime) -->
<span ef-text="efCart.total">$0.00</span>
<span ef-text="item.price">$0.00</span>
```

If you add or reorder these, the cart will still update correctly as long as you keep the placeholders or bindings in place. For more on this syntax, see [Frontend Template Engine — Syntax](/frontend-template-engine/syntax).

## Quantity controls

The cart plugin handles **−**, **+**, and **Remove** automatically via data attributes. No custom script is needed.

| Attribute | Element | Purpose |
| - | - | - |
| **`data-cart-qty-minus`** | Button | Decrease quantity by 1 |
| **`data-cart-qty-plus`** | Button | Increase quantity by 1 |
| **`data-cart-qty-remove`** | Button/link | Remove line (sets qty to 0) |
| **`data-code="[[ item.code ]]"`** | Same element | Links the button to the product |
| **`data-disable-when-one`** | Minus button (optional) | Disables the button when `item.quantity` is 1 (prevents accidentally removing the last unit) |

On checkout pages the minus button is always disabled at quantity 1, regardless of `data-disable-when-one`.

## Cart dropdown

The **Cart Dropdown** block gives you:

* A **trigger** (e.g. "Cart" plus the number of items) that visitors click to open the cart.
* A **panel** that opens below (or in a suitable position) with the full cart inside: same items, quantities, totals, and checkout link.

Show the item count in the trigger with **`[[ efCart.count ]]`**.

Use it when you want the cart in a fixed spot (e.g. header) without taking space until the visitor opens it.

## Checkout link

The cart plugin automatically resolves the checkout URL from your merchant settings and wires it to any element with the class **`.ef-cart-checkout`** or the attribute **`data-ef-cart-checkout`**. You do not need to hard-code the checkout URL in the builder.

The resolved URL is built as follows (in priority order):

1. The element's own `href` attribute (if it is a real path, not `#` or `#checkout`).
2. A `data-ef-cart-checkout-href` attribute on the element.
3. The checkout page configured in your merchant settings (injected as `window.efScope.checkout_url`).
4. Falls back to `/checkout` if nothing else resolves.

Current-page query parameters are automatically forwarded to the checkout URL (tracking/UTM parameters, etc.), with internal routing keys stripped.

<Info>
  The default Checkout button added by the builder already has `.ef-cart-checkout`. You only need to set a custom `href` if you want to override the merchant-configured checkout page.
</Info>

## Cart storage

The cart is stored in a **browser cookie** (`ef_cart_{brandId}`), not localStorage. Cookies persist for **365 days**, so the cart survives navigation and browser restarts within the same browser.

The cart is shared across all pages on the same domain, so the Cart Dropdown in the header and a full Cart block below the fold always show the same contents.

## JavaScript API

The cart plugin exposes a `window.ef` object you can call from custom scripts or `@click` handlers in your templates:

| Method | Description |
| - | - |
| **`window.ef.addToCart(code, options?, quantity?)`** | Add a product to the cart. If already in the cart, quantity increases. `options` can include `{ price, name, currency }`. |
| **`window.ef.setCartQuantity(code, quantity)`** | Set an absolute quantity. Pass `0` to remove the product. |
| **`window.ef.removeFromCart(code, allowClear?)`** | Decrease quantity by 1. When `allowClear` is `false` (default), does nothing if quantity is already 1 (prevents going to 0). |
| **`window.ef.getCart()`** | Returns the raw cart array `[{ code, quantity }, ...]` (for debugging or custom UI). |
| **`window.ef.getCartForSubmit()`** | Same as `getCart()` but excludes zero-quantity lines. |
| **`window.ef.onAddToCart(callback)`** | Run a callback when a product is added (client cart or `/b` buy links). Returns an unsubscribe function. See [EF API](/funnels/ef-api#cart). |

Example — add to cart on button click:

```html theme={null}
<button @click="window.ef.addToCart('BOTTLE-1')">Add to Cart</button>
```

Example — set quantity from an input:

```html theme={null}
<input type="number" @change="window.ef.setCartQuantity('BOTTLE-1', parseInt($event.target.value))" />
```

## `cart-updated` event

Every time the cart changes (add, remove, set quantity), the plugin dispatches a **`cart-updated`** custom event on `window`. You can listen to it to react to cart mutations in custom scripts:

```js theme={null}
window.addEventListener('cart-updated', (e) => {
  console.log('Cart changed:', e.detail.cart);
});
```

The event `detail` contains `{ brandId, cart }` where `cart` is the updated array. It bubbles, so
you can listen on either `window` or `document`.

The cart is **already rendered** when the event fires: `window.efScope` and every `[[ ]]`,
`ef-text`, `template-if` and `template-foreach` binding on the page hold the new cart by the time
your handler runs. That means reading the rendered values in the handler is safe:

```js theme={null}
window.addEventListener('cart-updated', () => {
  // The badge already shows the new count here.
  const badge = document.querySelector('[ef-text="efCart.count"]');
  badge.setAttribute('data-empty', parseInt(badge.textContent, 10) > 0 ? 'false' : 'true');
});
```

<Tip>
  Prefer `e.detail.cart` over reading the DOM when you only need the numbers — it is the same data
  without a layout read:

  ```js theme={null}
  window.addEventListener('cart-updated', (e) => {
    const count = e.detail.cart.reduce((n, item) => n + (item.quantity || 0), 0);
  });
  ```
</Tip>

<Tip>
  `cart-updated` fires on **any** cart change (add, remove, quantity). If you only care about items being **added** — and want the `/b` buy links covered too — use [`window.ef.onAddToCart(callback)`](/funnels/ef-api#cart) instead.
</Tip>

## Add-to-cart buttons

Buttons that add products to the cart use `data-ef-add-to-cart` (or class `.ef-add-to-cart`) together with `data-product-code`. These attributes also let the plugin read the price without an extra API request:

| Attribute | Purpose |
| - | - |
| **`data-product-code`** | Product code to add |
| **`data-ef-product-price`** | Unit price (numeric, e.g. `69.00`) |
| **`data-ef-product-name`** | Display name |
| **`data-ef-product-image`** | Image URL |
| **`data-ef-product-currency`** | Currency code (default `USD`) |
| **`data-ef-product-retail-price`** | Original/retail price for savings display |

When these attributes are present, adding to cart stores the price locally, so `item.price` and `item.total` are available immediately without waiting for the `/api/cart-products` response.

## Tips

* **Placement** – Put the cart or cart dropdown where visitors expect it (e.g. top-right for dropdown, above the fold for a full cart block).
* **Sticky / mobile** – You can place the cart in a sticky bar or in a mobile menu; the same block works anywhere.
* **Multiple carts** – You can add more than one cart or dropdown on a page; they all show the same cart data and stay in sync when the visitor changes quantity or adds items.
* **Item count badge** – Use `[[ efCart.count ]]` anywhere on the page (e.g. in the header next to "Cart") to show the total number of items in the cart.
* **Savings display** – Show `[[ efCart.discount_total ]]` in the cart footer or `[[ item.retail_price ]]` beside the unit price to highlight discounts when a retail price is set.
* **Subscription label** – Use `[[ item.is_subscription ]]` with `template-if` to show billing cadence (e.g. "Every 3 months") only for subscription products.
* **Bonuses & courses** – Use nested `template-foreach` on `item.bonuses` and `item.courses` to list included free products or digital courses beneath each cart line.


# Collection Item Tag
Source: https://docs.elasticfunnels.io/pages/collection-item-tag

Display dynamic content from collections using the collection-item tag

The `<collection-item>` tag allows you to display entries from a collection on your pages. Collections are reusable content sets (like testimonials, FAQs, features, etc.) that you can manage centrally and display dynamically.

## Overview

Collections are perfect for:

* Testimonials and reviews
* FAQ sections
* Feature lists
* Team member profiles
* Case studies
* Product benefits
* Any repeating content structure

The collection-item tag loops through all entries in a collection and displays them using your template.

## Basic Usage

### Simple Collection Display

```html theme={null}
<collection-item code="testimonials">
  <div class="testimonial">
    <p>{$content}</p>
    <p class="author">- {$author}</p>
  </div>
</collection-item>
```

### With Styling

```html theme={null}
<collection-item code="features" id="feature-item">
  <div class="feature-card">
    <h3>{$title}</h3>
    <p>{$description}</p>
    <img src="{$image_url}" alt="{$title}">
  </div>
</collection-item>
```

## Attributes

### Required Attributes

#### `code`

The collection code that identifies which collection to display.

**Format**: Any string that matches your collection code

**Example:**

```html theme={null}
<collection-item code="testimonials">
  <!-- Displays entries from the "testimonials" collection -->
</collection-item>
```

### Optional Attributes

#### `id`

Element ID applied to each collection entry wrapper.

**Example:**

```html theme={null}
<collection-item code="faq" id="faq-item">
  <!-- Each FAQ entry will be wrapped in <div id="faq-item"> -->
</collection-item>
```

## Collection Placeholders

Within the `<collection-item>` template, use `{$field_name}` to access collection entry fields.

### Placeholder Format

**Format**: `{$field_name}`

The `$` prefix indicates this is a collection field placeholder.

### Common Fields

Collection fields depend on how your collection is structured. Common examples include:

* `{$title}` - Entry title
* `{$content}` - Main content
* `{$description}` - Description text
* `{$author}` - Author name
* `{$image_url}` - Image URL
* `{$name}` - Name field
* `{$email}` - Email field
* `{$rating}` - Rating value
* `{$date}` - Date field

**Note**: Available fields depend on your collection structure. Check your collection settings to see available fields.

### Example with Multiple Fields

```html theme={null}
<collection-item code="testimonials">
  <div class="testimonial">
    <div class="rating">
      <!-- Display 5 stars based on rating -->
      <span>{$rating}/5</span>
    </div>
    <p class="quote">"{$content}"</p>
    <div class="author-info">
      <img src="{$author_image}" alt="{$author_name}">
      <div>
        <p class="author-name">{$author_name}</p>
        <p class="author-title">{$author_title}</p>
      </div>
    </div>
    <p class="date">{$date}</p>
  </div>
</collection-item>
```

## Complete Examples

### Testimonials Collection

```html theme={null}
<section class="testimonials">
  <h2>What Our Customers Say</h2>
  
  <collection-item code="customer-testimonials">
    <div class="testimonial-card">
      <div class="stars">
        <!-- Assuming rating is 1-5 -->
        <span>★★★★★</span>
      </div>
      <blockquote>
        <p>"{$content}"</p>
      </blockquote>
      <div class="author">
        <img src="{$customer_photo}" alt="{$customer_name}">
        <div>
          <p class="name">{$customer_name}</p>
          <p class="location">{$customer_location}</p>
        </div>
      </div>
    </div>
  </collection-item>
</section>
```

### FAQ Collection

```html theme={null}
<section class="faq">
  <h2>Frequently Asked Questions</h2>
  
  <collection-item code="faq-items">
    <details class="faq-item">
      <summary>{$question}</summary>
      <div class="answer">
        <p>{$answer}</p>
        <p class="category">Category: {$category}</p>
      </div>
    </details>
  </collection-item>
</section>
```

### Features Collection

```html theme={null}
<section class="features">
  <h2>Product Features</h2>
  
  <div class="features-grid">
    <collection-item code="product-features">
      <div class="feature">
        <div class="feature-icon">
          <img src="{$icon_url}" alt="{$title}">
        </div>
        <h3>{$title}</h3>
        <p>{$description}</p>
        <ul>
          <li>{$benefit_1}</li>
          <li>{$benefit_2}</li>
          <li>{$benefit_3}</li>
        </ul>
      </div>
    </collection-item>
  </div>
</section>
```

### Team Members Collection

```html theme={null}
<section class="team">
  <h2>Our Team</h2>
  
  <div class="team-grid">
    <collection-item code="team-members">
      <div class="team-member">
        <img src="{$photo_url}" alt="{$name}">
        <h3>{$name}</h3>
        <p class="role">{$role}</p>
        <p class="bio">{$bio}</p>
        <div class="social">
          <a href="{$linkedin_url}">LinkedIn</a>
          <a href="{$twitter_url}">Twitter</a>
        </div>
      </div>
    </collection-item>
  </div>
</section>
```

## Styling Collections

### CSS Grid Layout

```html theme={null}
<style>
  .collection-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
    gap: 20px;
    padding: 20px;
  }
  
  .collection-item {
    border: 1px solid #ddd;
    border-radius: 8px;
    padding: 20px;
  }
</style>

<div class="collection-grid">
  <collection-item code="features" id="collection-item">
    <div class="collection-item">
      <h3>{$title}</h3>
      <p>{$description}</p>
    </div>
  </collection-item>
</div>
```

### Flexbox Layout

```html theme={null}
<style>
  .collection-list {
    display: flex;
    flex-direction: column;
    gap: 15px;
  }
</style>

<div class="collection-list">
  <collection-item code="testimonials">
    <div class="testimonial">
      <p>{$content}</p>
      <p>- {$author}</p>
    </div>
  </collection-item>
</div>
```

## How It Works

1. **Collection Lookup**: The system finds the collection by the `code` attribute
2. **Entry Retrieval**: All entries from that collection are retrieved
3. **Template Rendering**: For each entry, the template is rendered
4. **Placeholder Replacement**: Collection placeholders (`{$field_name}`) are replaced with entry data
5. **Output**: Each entry is wrapped in a `<div>` with the specified `id` (if provided)

## Managing Collections

Collections are managed in your dashboard:

1. **Create Collection**: Go to Collections → Create Collection
2. **Define Fields**: Set up the fields your collection entries will have
3. **Add Entries**: Add individual entries to your collection
4. **Use Code**: Use the collection code in your `<collection-item>` tags

### Collection Structure

When creating a collection, you define:

* **Collection Code**: The identifier used in `code="..."` attribute
* **Fields**: Custom fields for each entry (title, content, image, etc.)
* **Entries**: Individual items in the collection

## Best Practices

### Content Organization

* **Logical Grouping**: Group related content into collections
* **Consistent Structure**: Keep entry fields consistent within a collection
* **Reusable Content**: Use collections for content you'll display in multiple places

### Template Design

* **Responsive**: Design templates that work on all devices
* **Consistent Styling**: Keep styling consistent across entries
* **Flexible Layout**: Design templates that work with varying content lengths

### Performance

* **Limit Entries**: Don't create collections with hundreds of entries if you only need a few
* **Optimize Images**: Ensure collection images are optimized
* **Cache Considerations**: Collections are rendered server-side for performance

## Troubleshooting

### No Entries Displaying

**Possible Causes:**

* Collection code doesn't exist
* Collection has no entries
* Collection code is misspelled

**Solutions:**

* Verify the collection code in your dashboard
* Check that the collection has entries
* Ensure the `code` attribute matches exactly (case-sensitive)

### Placeholders Not Replacing

**Issue**: Placeholders show as literal text (e.g., `{$title}`)

**Solutions:**

* Check placeholder spelling (case-sensitive)
* Ensure you're using `{$field_name}` format with `$` prefix
* Verify the field exists in your collection structure
* Check that entries have values for those fields

### Missing Fields

**Issue**: Some fields are empty

**Solutions:**

* Verify the field name matches your collection structure
* Check that entries have values for those fields
* Ensure field names are spelled correctly (case-sensitive)

## Related Documentation

* [Product Item Tag](/pages/product-item-tag) - Display product listings
* [Page Variables](/pages/page-variables) - Use variables and placeholders
* [Containers](/pages/containers) - Dynamic content containers


# Containers
Source: https://docs.elasticfunnels.io/pages/containers

Specialized containers for dynamic content, lazy loading, split testing, and conditional displays

Containers control when and how content appears to visitors. Use them for conditional visibility, lazy loading, split tests, and visitor-specific content.

## Overview

Containers wrap page content and add behavior based on visitor actions, page events, or other conditions.

## Available Containers

### CTA Container

The **CTA Container** (Call-to-Action Container) is hidden by default and only appears when the CTA is triggered, typically used to reveal purchase buttons, pricing tables, or order forms after a visitor watches your Video Sales Letter (VSL).

**Key Features:**

* Hidden by default (`display: none`)
* Transforms to visible (`display: block`) when CTA is executed
* Can persist once triggered during the session
* Commonly contains buy buttons, pricing, checkout forms

**How to Trigger:**

The CTA can be executed in three ways:

1. **VSL CTA**: At a specific timestamp in your Video Sales Letter, you call `getStarted()` to trigger the CTA when that point is reached in the video
2. **Manual Button Click**: Add a button with click interaction that executes `getStarted()` JavaScript function
3. **Timed Event**: Use Page Events with JavaScript to execute `getStarted()` after a delay

**Example Button Click Setup:**

```javascript theme={null}
// In Interactions Panel (Ctrl+I) on your button:
// Trigger: On Click
// Action: Execute JavaScript

getStarted();
```

**Common Use Cases:**

* Reveal order button after VSL completes
* Show pricing after engagement threshold
* Display purchase options on manual trigger
* Progressive disclosure of sales information

<Note>
  The CTA Container uses the `getStarted()` global function which is available throughout your page. Once triggered, the container can remain visible for the visitor's session.
</Note>

***

### Hide on CTA Container

The **Hide on CTA Container** is the opposite of the CTA Container - it's visible by default and gets hidden when the CTA is executed.

**Key Features:**

* Visible by default
* Hides automatically when `getStarted()` is executed
* Useful for removing content that shouldn't appear with purchase options
* Often used in conjunction with CTA Container

**How It Works:**

When `getStarted()` is called (via VSL, button, or JavaScript), this container automatically hides while the CTA Container shows.

**Common Use Cases:**

* Hide video player when purchase form appears
* Remove promotional content after CTA
* Clear page space for checkout elements
* Move visitors from sales content to the purchase step without extra clutter

**Example Pattern:**

```
Before CTA:
  ✓ Hide on CTA Container (visible) - Contains VSL video
  ✗ CTA Container (hidden) - Contains buy button

After CTA triggered:
  ✗ Hide on CTA Container (hidden) - VSL disappears
  ✓ CTA Container (visible) - Buy button appears
```

<Tip>
  Use both containers together to create smooth transitions from your sales content to purchase forms. This creates a clean, focused buying experience.
</Tip>

***

### Merchant Container

The **Merchant Container** displays content conditionally based on the active payment processor (merchant) for the current page view.

**Key Features:**

* Shows content only for specific merchants
* Hides all non-matching merchant containers
* Can be set per domain or overridden in Page Events
* Useful for merchant-specific disclaimers, policies, and branding

**How Merchants Are Determined:**

1. **Domain-Level Setting**: Default merchant set in Domain settings
2. **Page Events Override**: Use the "Set Merchant" node in Page Events to override for specific conditions

**Supported Merchants:**

* Buygoods
* Clickbank
* Digistore24
* Other configured payment processors

**Configuration:**

1. **Add Merchant Container** to your page
2. **Select Merchant** from the container settings
3. **Add Content** specific to that merchant
4. **Repeat** for each merchant you want to support

**Example Scenario:**

You have different footer disclaimers specific to each merchant:

```
Page contains:
  - Merchant Container (Buygoods) → Buygoods-specific disclaimer and policies
  - Merchant Container (Clickbank) → Clickbank-specific disclaimer and policies
  - Merchant Container (Digistore24) → Digistore24-specific disclaimer and policies

When visitor arrives:
  - Domain merchant = Buygoods
  → Only Buygoods disclaimer displays

Override in Page Events:
  - Query Parameter (affiliate_id = 100)
  → Set Merchant to Clickbank
  → Only Clickbank disclaimer displays
```

**Common Use Cases:**

* Merchant-specific disclaimers and legal policies
* Payment processor-specific trust badges and seals
* Different refund policies based on merchant
* Merchant-specific support information and contact details
* Custom branding elements per merchant
* Merchant-specific terms and conditions

**Setting Merchant in Page Events:**

Use the **Set Merchant** node to dynamically change which merchant container displays:

1. Go to **Page Events** for your page
2. Add a condition (Query Parameter, Script Rule, etc.)
3. Connect to **Set Merchant** node
4. Select the merchant to activate
5. Merchant containers will show/hide accordingly

**Resetting Merchant:**

Use the **Clear Merchant** node to reset back to the domain's default merchant:

1. Add **Clear Merchant** node in Page Events
2. Connect it to a condition or event
3. When triggered, clears any session merchant override
4. Page returns to using the domain's default merchant

This is useful for:

* Resetting test merchants back to production
* Clearing affiliate-specific merchants after purchase
* Returning to default after special conditions expire

<Note>
  If no merchant is set (neither at domain level nor via Page Events), merchant containers will not display. Ensure you have a default merchant configured.
</Note>

***

### Split Test Container

The **Split Test Container** marks a section of the page whose content is chosen by a traffic split. It renders as a `<split-test>` element and holds no logic of its own — the variants and their weights live in **Page Events**.

**Key Features:**

* Marks one swappable slot, identified by its `id`
* Filled by a **Component Split Test** node in Page Events
* Its inner content is the **default** — what renders when no split test is running
* Each served variant is tagged for analytics (`data-sid` / `data-cid`)

<Warning>
  Exactly one of two things renders: the component the graph selected (replacing the container, wrapper and all), or — when nothing is bound — the default content on its own. So **never write the variants inline** inside the container; they can never all render. A single component inside a container is fine, because that is just the default.

  Containers are also filled **before** both template engines run, so wrapping one in `@if` or `<template-if>` does not stop it being filled — it only hides the result after the visitor has already been enrolled in the test. See [Rendering pipeline](/pages/rendering-pipeline).
</Warning>

**How to Use:**

1. **Add a Split Test Container** to your page and fill in its **Split Test Container Name** trait — that name is what you pick from in Page Events.
2. **Create one saved component per variant.**
3. **Configure in Page Events**:
   * Add a **Component Split Test** node and select the container
   * Set **Total Variants** — a **Traffic Distribution** node is created for each one
   * Attach one **Component** node under each Traffic Distribution node, and mark one as the baseline
4. **Track Results** in Analytics

<Warning>
  Variants attach to **Component** nodes, not Dynamic Content nodes. `Component Split Test → Traffic Distribution → Component` is the only valid chain; the builder rejects anything else.
</Warning>

**Common Use Cases:**

* Test different headlines
* Compare pricing presentations
* Test different images or videos
* Optimize form layouts

**Best Practices:**

* Test one element at a time
* Run tests long enough for statistical significance
* Track meaningful conversion goals
* Document your test results

<Tip>
  For complete split testing documentation, including setup and analysis, see [Split Testing](/funnels/split-testing).
</Tip>

***

### Lazy Load Container

The **Lazy Load Container** defers loading of content inside it until the visitor scrolls to that section of the page.

**Key Features:**

* Improves initial page load performance
* Loads content "just in time" when visitor scrolls near it
* Reduces bandwidth for content visitors never see
* Loads when needed without interrupting the page

**How It Works:**

1. Page loads with empty lazy load containers
2. Visitor scrolls down the page
3. When container enters viewport (or approaches it), content loads
4. Content appears smoothly without page disruption

**What to Lazy Load:**

* Below-the-fold content
* Large images or videos
* Comment sections
* Secondary information
* Resource-heavy widgets or embeds

**What NOT to Lazy Load:**

* Above-the-fold content
* Critical purchase buttons
* Forms that need immediate interaction
* Content needed for SEO

**Performance Tips:**

* Use for content below the fold only
* Combine with image optimization
* Test on slow connections
* Monitor Core Web Vitals impact

<Warning>
  Don't lazy load critical conversion elements like buy buttons or lead capture forms. Visitors should be able to interact with these immediately.
</Warning>

***

## Related Containers

Some specialized containers are documented in dedicated pages:

### Subscription Containers

**Sub Pending**, **Sub Success**, and **Sub Error** containers auto-toggle based on the result of a subscription modification API call (`ef.sub.upgrade()` / `ef.sub.cancel()`). Use them to build multi-screen subscription upsell flows.

[View Subscription Upsells Documentation →](/products/subscription-upsells)

### Dynamic Container

The **Dynamic Container** marks a slot whose content is replaced with a saved component when a Page Events condition matches. Unlike the Split Test Container, the choice is driven by a **condition you write**, not by a traffic split.

[View Dynamic Content Documentation →](/funnels/dynamic-content)

### Whitelisted Containers

**Whitelisted Container** and **Non-Whitelisted Container** display different content based on visitor whitelisting status, commonly used for content protection and personalized visitor experiences.

[View Content Visibility Control Documentation →](/pages/visitor-based-content)

***

## Container Combination Patterns

### Progressive Sales Flow

Combine multiple containers for a complete sales experience:

```
Initial Page Load:
  ✓ Hide on CTA Container
    - VSL video
    - Sales copy
  ✗ CTA Container (hidden)
    - Pricing
    - Buy button

After VSL triggers CTA:
  ✗ Hide on CTA Container (hidden)
  ✓ CTA Container (visible)
    - Pricing
    - Buy button
    ✓ Merchant Container (Buygoods)
      - Buygoods disclaimer
    ✗ Merchant Container (Clickbank) - hidden
```

### Performance-Optimized Page

Use lazy loading for better page speed:

```
Above the fold:
  - Hero section (loads immediately)
  - VSL player (loads immediately)
  - CTA button (loads immediately)

Below the fold (lazy loaded):
  ✓ Lazy Load Container
    - Testimonials section
    - FAQ accordion
    - Detailed features
    - Footer content
```

### Dynamic Merchant Selection

Adapt disclaimers and policies based on traffic source:

```
Page Events Flow:
  1. On Page Load
  2. Query Parameter Condition (source = partner1)
     → Set Merchant to Buygoods
  3. Query Parameter Condition (source = partner2)
     → Set Merchant to Clickbank
  4. Default
     → Domain default merchant

Result:
  - Only matching merchant container displays
  - Visitor sees appropriate disclaimers and policies
```

***

## Best Practices

### Container Organization

1. **Clear Naming**: Name containers descriptively in the page builder
2. **Document Logic**: Note which containers work together
3. **Test All Paths**: Verify all show/hide conditions work correctly
4. **Consider Mobile**: Ensure container behaviors work on all devices

### Performance Guidelines

1. **Lazy Load Wisely**: Use for below-fold content only
2. **Minimize Nesting**: Don't nest containers unnecessarily
3. **Test Load Times**: Monitor impact on page speed
4. **Optimize Content**: Compress images and minimize resources inside containers

### User Experience

1. **Smooth Transitions**: Avoid jarring content shifts when containers appear
2. **Visual Feedback**: Let users know when content is loading
3. **Fallback Content**: Have defaults for when conditions aren't met
4. **Test Edge Cases**: What happens if no merchant is set? Test it.

### Development Workflow

1. **Start Simple**: Add containers one at a time
2. **Test Immediately**: Verify each container works before adding more
3. **Use Preview Mode**: Test without affecting live traffic
4. **Clear Cache**: Clear browser cache when testing changes

***

## Troubleshooting

### CTA Container Not Showing

**Symptoms**: CTA container remains hidden after trigger

**Possible Causes:**

* `getStarted()` not being called correctly
* JavaScript errors preventing execution
* Container selector issues

**Solutions:**

1. Check browser console for JavaScript errors
2. Verify button click triggers `getStarted()`
3. Test VSL CTA timestamp is reached
4. Confirm container has correct ID/class

### Merchant Container Not Displaying

**Symptoms**: No merchant containers showing

**Possible Causes:**

* No merchant set at domain level
* No merchant selected in Page Events
* Merchant ID mismatch

**Solutions:**

1. Check domain settings for default merchant
2. Verify Set Merchant node in Page Events
3. Confirm merchant containers have correct merchant assigned
4. Check browser console for errors

### Lazy Load Issues

**Symptoms**: Content not loading when scrolling

**Possible Causes:**

* Container too small to trigger
* JavaScript not initializing properly
* Content inside container has errors

**Solutions:**

1. Ensure container has minimum height
2. Check browser console for errors
3. Test without lazy loading first
4. Verify content loads normally outside container

### Multiple Containers Conflicting

**Symptoms**: Unexpected show/hide behavior

**Possible Causes:**

* Overlapping container logic
* Multiple merchants set incorrectly
* CTA and Hide on CTA not paired properly

**Solutions:**

1. Review Page Events flow carefully
2. Test each container individually
3. Check for conflicting JavaScript
4. Simplify logic and add complexity gradually

***

## Related Documentation

* [Page Events](/funnels/page-events) - Set up merchant switching and complex flows
* [Dynamic Content](/funnels/dynamic-content) - Learn about Dynamic Containers
* [Content Visibility Control](/pages/visitor-based-content) - Whitelisting containers
* [Split Testing](/funnels/split-testing) - A/B testing with containers
* [Interactions Panel](/pages/interactions-panel) - Add click handlers to trigger CTAs

<Note>
  Start with one clear container use case, then add more logic only when you can test each condition.
</Note>


# Create Landing Page
Source: https://docs.elasticfunnels.io/pages/create-landing-page

Choose how to create a page: templates, visual builder, code, AI tools, and checkout paths

A landing page is where someone lands from ads or email. On **Create Your Landing Page**, choose how you want to start: AI, a cloned URL, a template, the drag-and-drop builder, the code editor, or a checkout page when your brand supports it.

## Open Create Page

1. In the sidebar, open **Pages**.
2. Click **Create Page**.

**What you see on Create Your Landing Page**

* **AI Page Builder** creates a first draft from your prompt.
* **AI Page Cloner** turns a public URL into an editable page. Some plans may need an upgrade.
* **Arbitrage Page Builder** starts the arbitrage builder flow.
* **Drag and Drop Builder** opens page details, then the visual builder.
* **Choose Template** opens the template library.
* **Checkout Page** appears only when checkout is set up for the brand.
* **Code Editor** opens page details, then HTML, CSS, and JavaScript.

Pick a card to start. If you open a path and want a different one, use **Back** to return to this screen.

## AI Page Builder (recommended, beta)

Describe the page you want. ElasticFunnels creates a draft you can edit in the builder.

## AI Page Cloner and Arbitrage Page Builder

**AI Page Cloner** imports a public URL into an editable page. If your plan does not include it, the app prompts you to upgrade.

**Arbitrage Page Builder** starts a guided flow for arbitrage-style landers.

## Or build it yourself

**Drag and Drop Builder** asks for **page details** first: title, slug, status, and domain when your project uses domains. After you save, you build visually.

**Choose Template** opens the template library. Pick a layout, then finish the prompts.

**Checkout Page** only appears when your brand is set up for checkouts and payments. It starts from checkout-focused templates.

**Code Editor** asks for **page details**, then opens HTML, CSS, and JavaScript.

## Shared template links

If you open a **shared template** or clone link, the clone flow starts for you automatically. Complete the fields on that screen to create your copy.

## Page Builder Tips

* **Start from a template** when you want structure from day one.
* **Keep one main action** per page so visitors know what to do.
* **Headlines** should state the benefit in plain language.
* **Social proof** (reviews, quotes) belongs near the decision point.
* **Check mobile** in preview before you publish.
* **Keep images lean** so the page stays quick.

For a wider tour of page features, see [Pages Overview](/pages/overview).

## Best Practices

* One clear goal per page.
* Buttons that stand out from the background.
* Trust cues where people hesitate (guarantee, support, security).
* Copy that answers "what do I get?"
* Images that support the story, not decoration only.


# Interactions Panel
Source: https://docs.elasticfunnels.io/pages/interactions-panel

Add interactive behaviors to your page elements with clicks, hovers, animations, and custom JavaScript

Use the Interactions Panel to add clicks, hovers, animations, form actions, and custom JavaScript to page elements.

<Note>
  Access the Interactions Panel by selecting an element and pressing **Ctrl+I**, or through the right sidebar when an element is selected.
</Note>

## Quick Start

### Basic Usage Flow

1. **Select an Element**: Click on any element in your page editor
2. **Open Interactions Panel**: Press **Ctrl+I** or find it in the right sidebar
3. **Add a Trigger**: Click "Add \[Device] Trigger" and choose when the interaction should happen
4. **Choose an Action**: Select what should happen when the trigger fires
5. **Configure Settings**: Customize the behavior with specific parameters
6. **Test**: Preview your page to see the interaction in action

### Common Example: Execute JavaScript on Click

```javascript theme={null}
// Example: Simple alert on button click
alert('Button clicked!');

// Example: Change element content
document.getElementById('my-text').innerHTML = 'Content changed!';

// Example: Show/hide elements
document.getElementById('hidden-section').style.display = 'block';
```

### Getting Element IDs for Targeting

When you need to target specific elements (for show/hide actions, JavaScript code, etc.), you can easily copy their element IDs:

1. **Select the target element** in the page builder
2. **Hover over "Component Settings"** text in the right sidebar
3. **Click the copy link** that appears on hover to copy the element ID
4. **Paste the ID** into your interaction configuration

This is especially useful for:

* Show/Hide Element actions
* Toggle Visibility actions
* Custom JavaScript that targets specific elements
* Focus on Element actions

## Device-Specific Behavior

### Device Detection System

The system automatically detects the current device based on screen width:

#### **Mobile Portrait**

* **Screen Width**: ≤ 575px
* **Device ID**: `mobilePortrait`
* **Typical Devices**: Mobile phones in portrait mode

#### **Tablet**

* **Screen Width**: 576px - 992px
* **Device ID**: `tablet`
* **Typical Devices**: Tablets, mobile phones in landscape, small laptops

#### **Desktop**

* **Screen Width**: > 992px
* **Device ID**: `desktop`
* **Typical Devices**: Desktop computers, large laptops

### Cascading Rules System

The interactions system uses a **cascading inheritance model** where interactions flow down from larger to smaller devices:

**Desktop interactions execute on**: Desktop, Tablet, Mobile Portrait (unless overridden)\
**Tablet interactions execute on**: Tablet, Mobile Portrait (unless overridden)\
**Mobile Portrait interactions execute on**: Mobile Portrait only

This ensures your interactions work across all devices while allowing device-specific customization.

### Override and Disable System

When viewing tablet or mobile in the panel, you'll see desktop interactions that will execute unless specifically overridden:

#### **Override Button**

* Creates a device-specific version of the interaction
* Allows you to customize behavior for that device
* The override takes precedence over the cascaded interaction

#### **Disable Button**

* Prevents the desktop interaction from executing on this device
* Useful when an interaction doesn't make sense on smaller screens
* Creates a "disabled" action that blocks the cascaded interaction

### Dynamic Device Changes

The system automatically handles device changes:

* **Responsive Design**: When users resize their browser or rotate their device
* **Automatic Re-evaluation**: Interactions are re-evaluated for the new device size
* **No Page Reload**: Device changes update without refreshing the page
* **Duplicate Prevention**: The system prevents duplicate event listeners during device transitions

<Warning>
  Desktop interactions will execute on all devices unless specifically overridden or disabled. This cascading behavior ensures your interactions work across all screen sizes while giving you complete control over device-specific behavior.
</Warning>

## Available Triggers

### Mouse & Touch Interactions

#### **On Click**

* **Description**: Triggers when the element is clicked or tapped
* **Use Cases**: Button actions, navigation, form submissions
* **Best For**: Primary user interactions

#### **On Hover**

* **Description**: Triggers when mouse hovers over the element
* **Use Cases**: Tooltips, preview content, hover effects
* **Note**: May not work on touch devices

#### **On Mouse Enter**

* **Description**: Triggers when mouse cursor enters the element area
* **Use Cases**: Show additional information, highlight effects
* **Difference from hover**: More precise control over enter/leave events

#### **On Mouse Leave**

* **Description**: Triggers when mouse cursor leaves the element area
* **Use Cases**: Hide tooltips, reset animations, cleanup actions

### Focus & Form Interactions

#### **On Focus**

* **Description**: Triggers when the element gains focus
* **Best For**: Input fields, buttons, interactive elements
* **Use Cases**: Show help text, highlight sections, form validation

#### **On Blur**

* **Description**: Triggers when the element loses focus
* **Best For**: Input fields, form elements
* **Use Cases**: Validate input, hide help text, save data

#### **On Form Submit**

* **Description**: Triggers when a form is submitted
* **Available On**: Form elements only
* **Use Cases**: Custom validation, tracking, additional processing

#### **On Form Success**

* **Description**: Triggers when form submission is successful
* **Available On**: Form elements only
* **Use Cases**: Show success messages, redirect, track conversions

#### **On Form Error**

* **Description**: Triggers when form submission fails
* **Available On**: Form elements only
* **Use Cases**: Show error messages, retry logic, error tracking

### Other Triggers

#### **On Scroll**

* **Description**: Triggers when the element is scrolled
* **Use Cases**: Lazy loading, scroll animations, progress indicators

#### **On Load**

* **Description**: Triggers when the element finishes loading
* **Best For**: Images, iframes, media elements
* **Use Cases**: Show content after loading, initialize components

## Available Actions

### Modal Controls

#### **Show Modal**

* **Description**: Display a modal dialog
* **Configuration**: Select which modal to show
* **Use Cases**: Product details, contact forms, confirmations

#### **Hide Modal**

* **Description**: Close a modal dialog
* **Configuration**: Select which modal to hide
* **Use Cases**: Close buttons, overlay clicks, form completion

### Element Visibility

#### **Show Element**

* **Description**: Make a hidden element visible
* **Configuration**: CSS selector of target element
* **Use Cases**: Reveal hidden content, show form fields

#### **Hide Element**

* **Description**: Hide a visible element
* **Configuration**: CSS selector of target element
* **Use Cases**: Collapse sections, hide form fields

#### **Toggle Visibility**

* **Description**: Switch between hidden and visible states
* **Configuration**: CSS selector of target element
* **Use Cases**: Expandable sections, show/hide toggles

### Tracking & Analytics

#### **Track Split Test Goal**

* **Description**: Record a conversion goal for split testing
* **Configuration**: Goal value (e.g., "purchase", "signup")
* **Use Cases**: Track conversions, measure variant performance

#### **Track Event**

* **Description**: Send tracking events to analytics platforms
* **Configuration**: Event name selection
* **Platforms**: Google Analytics, Meta Ads, Google Ads
* **Common Events**: Lead, AddToCart, Purchase, Contact, Subscribe

#### **Custom Meta Event**

* **Description**: Send custom events to Meta (Facebook) Ads
* **Configuration**: Event name and value
* **Use Cases**: Custom conversion tracking, audience building

#### **Custom GA Event**

* **Description**: Send custom events to Google Analytics
* **Configuration**: Event name and value
* **Use Cases**: Custom tracking, behavior analysis

### JavaScript Execution

#### **Execute JavaScript**

* **Description**: Run custom JavaScript code using the browser's JavaScript engine
* **Configuration**: Code editor with syntax highlighting
* **Execution**: Code is executed using `eval()` with access to the global scope
* **Error Handling**: JavaScript errors are caught and logged to the browser console
* **Use Cases**: Custom functionality, API calls, complex interactions, DOM manipulation

**Example Use Cases:**

```javascript theme={null}
// Show/hide elements
document.getElementById('section').style.display = 'block';

// Change content
document.querySelector('.title').textContent = 'New Title';

// API calls
fetch('/api/data').then(response => response.json()).then(data => {
    console.log(data);
    document.getElementById('results').innerHTML = data.message;
});

// Form manipulation and validation
const emailField = document.getElementById('email');
emailField.value = 'user@example.com';
emailField.focus();

// Check if elements exist before manipulating them
if (document.getElementById('my-element')) {
    document.getElementById('my-element').style.display = 'block';
}

// Wait for elements to load if needed
setTimeout(() => {
    document.getElementById('delayed-element').innerHTML = 'Updated!';
}, 1000);
```

**Security and Performance Notes:**

* Code executes with full access to the page and global JavaScript scope
* All JavaScript errors are caught and logged for debugging
* Code execution is immediate when the trigger fires
* Consider performance impact for complex operations

### Element Focus

#### **Focus on Element**

* **Description**: Set focus to a specific element
* **Configuration**: CSS selector of target element
* **Use Cases**: Improve accessibility, guide user attention

### Animations

#### **Slide Animations**

* **Slide Up**: Element slides upward
* **Slide Down**: Element slides downward
* **Slide Left**: Element slides to the left
* **Slide Right**: Element slides to the right
* **Configuration**: Duration, distance, easing function

#### **Fade Animations**

* **Fade In**: Element fades into view
* **Fade Out**: Element fades out of view
* **Configuration**: Duration, easing function

#### **Scale Animations**

* **Scale Up**: Element grows larger
* **Scale Down**: Element shrinks smaller
* **Configuration**: Duration, scale factor, easing function

#### **Rotation Animations**

* **Rotate Clockwise**: Element rotates clockwise
* **Rotate Counter**: Element rotates counter-clockwise
* **Configuration**: Duration, rotation degrees, easing function

#### **Special Effects**

* **Bounce In**: Element bounces into view
* **Shake**: Element shakes horizontally
* **Pulse**: Element pulses in size
* **Flip**: Element flips around
* **Configuration**: Duration, easing function

### Animation Settings

All animations can be customized with:

* **Duration**: Animation length in milliseconds (default: 300ms)
* **Easing**: Animation timing function
  * ease, ease-in, ease-out, ease-in-out
  * linear, cubic-bezier curves
* **Target Element**: Animate a different element (optional)

## Configuration Options

### Action-Specific Settings

#### Modal Actions

* **Modal Selection**: Choose from available modals on your page
* **Auto-close**: Configure automatic closing behavior

#### Event Tracking

* **Event Name**: Select from common events or enter custom names
* **Goal Value**: Optional conversion value for split testing
* **Platform Targeting**: Events automatically sent to connected platforms

#### Custom JavaScript

* **Code Editor**: Full-featured editor with syntax highlighting
* **Error Handling**: Console integration for debugging
* **Scope**: Access to page elements and global variables

#### Element Targeting

* **CSS Selectors**: Use ID (#element), class (.class), or complex selectors
* **Copy Element IDs**: Hover over "Component Settings" in the right sidebar to copy any element's ID
* **Validation**: Real-time validation of selector syntax
* **Multiple Elements**: Target multiple elements with class selectors

#### Animation Controls

* **Duration**: Fine-tune animation timing
* **Easing Functions**: Choose from predefined or custom curves
* **Chaining**: Combine multiple animations for complex effects

## Best Practices

### Performance Optimization

1. **Minimize JavaScript**: Keep custom code lightweight and efficient
2. **Use Animations Sparingly**: Too many animations can impact performance
3. **Test on Mobile**: Ensure interactions work well on touch devices
4. **Optimize Selectors**: Use efficient CSS selectors for targeting elements
5. **Consider Event Frequency**: Avoid high-frequency events like scroll for heavy operations

### User Experience Guidelines

1. **Provide Visual Feedback**: Users should know when interactions occur
2. **Maintain Accessibility**: Ensure interactions work with keyboard navigation
3. **Consider Touch Devices**: Hover effects don't work on mobile
4. **Test Across Devices**: Verify interactions work on all target devices

### Development Workflow

1. **Start with Desktop**: Create your primary interactions on desktop first
2. **Test Mobile Early**: Check how interactions behave on smaller screens
3. **Use Override System**: Create device-specific versions when needed
4. **Preview Frequently**: Test interactions in preview mode regularly

### Common Patterns

#### Button Click Handlers

```javascript theme={null}
// Track button clicks
gtag('event', 'click', {
    event_category: 'button',
    event_label: 'cta-button'
});

// Show confirmation
alert('Thank you for your interest!');
```

#### Form Enhancement

```javascript theme={null}
// Auto-fill form fields
document.getElementById('country').value = 'United States';

// Validate before submission
const email = document.getElementById('email').value;
if (!email.includes('@')) {
    alert('Please enter a valid email address');
    return false;
}
```

#### Dynamic Content

```javascript theme={null}
// Update content based on user action
document.querySelector('.dynamic-text').innerHTML = 'Content updated!';

// Show/hide sections
document.getElementById('advanced-options').style.display = 'block';
```

## Device-Specific Examples

### Desktop-Only Interactions

* **Hover Effects**: Use "On Hover" triggers for rich tooltips and preview content
* **Complex Animations**: Multi-step animations that work better on larger screens
* **Advanced JavaScript**: Complex form validation or API interactions

### Mobile-Specific Interactions

* **Touch-Friendly Actions**: Larger click targets and simplified interactions
* **Simplified Animations**: Lighter animations for better mobile performance
* **Mobile-Specific Content**: Show mobile-optimized content or navigation

### Responsive Strategies

* **Start with Desktop**: Create your main interactions on desktop first
* **Test Mobile Early**: Preview how desktop interactions work on mobile
* **Override When Needed**: Create mobile-specific versions for better UX
* **Disable Hover Effects**: Disable hover interactions that don't work on touch devices

## Troubleshooting

### Common Issues

#### Interactions Not Triggering

* **Wrong Element Selected**: Make sure you selected the correct element before adding the interaction
* **Device Mismatch**: Check if the interaction is set for the device you're testing on
* **Element Missing**: Verify the target element exists and has a unique ID
* **JavaScript Errors**: Check browser console for error messages

#### JavaScript Code Issues

* **Syntax Errors**: Check your JavaScript code syntax in the browser console first
* **Missing Elements**: Make sure elements you're targeting in your code actually exist
* **Timing Issues**: Some elements may not be available when your code runs

#### Device-Specific Issues

* **Desktop vs Mobile**: Desktop interactions run on all devices unless you override them
* **Touch vs Mouse**: Hover effects don't work on touch devices
* **Screen Size**: Device detection is based on screen width (575px and 992px breakpoints)

#### Show/Hide Element Issues

* **Invalid Selectors**: Make sure your CSS selectors are correct (e.g., `#element-id`, `.class-name`)
* **Element Not Found**: Verify the target element exists on the page
* **ID Spelling**: Check that element IDs are spelled correctly and match exactly
* **Need Element ID?**: Hover over "Component Settings" in the right sidebar to copy any element's ID

### Debugging Tips

#### **Testing Your Interactions**

1. **Preview Mode**: Always test interactions in live preview mode
2. **Browser Console**: Check for error messages if interactions aren't working
3. **Device Testing**: Use browser dev tools to simulate different screen sizes
4. **Step-by-Step Testing**: Test each interaction individually before combining multiple

#### **Common Debugging Steps**

1. **Verify Element Selection**: Make sure you selected the correct element in the editor
2. **Check Device Settings**: Confirm the interaction is set for the right device
3. **Test JavaScript Code**: For custom JavaScript, test your code in the browser console first
4. **Validate Selectors**: For show/hide actions, ensure your CSS selectors are correct
5. **Check Element IDs**: Make sure target elements have unique IDs

#### **Quick Fixes**

* **Interaction not working**: Check browser console for error messages
* **Wrong device behavior**: Verify device settings in the interactions panel
* **JavaScript errors**: Test your code syntax in browser console
* **Element not found**: Double-check element IDs and CSS selectors

## Advanced Use Cases

### API Integration

```javascript theme={null}
// Fetch data from external API
fetch('https://api.example.com/data')
    .then(response => response.json())
    .then(data => {
        document.getElementById('results').innerHTML = data.message;
    });
```

### Form Validation

```javascript theme={null}
// Custom form validation
function validateForm() {
    const email = document.getElementById('email').value;
    const phone = document.getElementById('phone').value;
    
    if (!email || !phone) {
        alert('Please fill in all required fields');
        return false;
    }
    
    return true;
}
```

### Dynamic Content Updates

```javascript theme={null}
// Update content based on user selection
const selection = document.getElementById('product-select').value;
document.getElementById('price-display').textContent = '$' + getPriceForProduct(selection);
```

## Security Considerations

### Safe JavaScript Practices

1. **Validate Input**: Always validate user input before processing
2. **Sanitize Data**: Clean data before displaying in HTML
3. **Limit Scope**: Don't expose sensitive information in client-side code
4. **Test Thoroughly**: Verify interactions work as expected without security risks

### Content Security Policy

* **Script Sources**: Ensure custom JavaScript complies with CSP
* **External APIs**: Only connect to trusted external services
* **User Data**: Handle user data responsibly and securely

<Warning>
  Custom JavaScript executes in the user's browser with access to page content. Always test thoroughly and follow security best practices when implementing custom interactions.
</Warning>

## Related Documentation

* [Split Testing](/funnels/split-testing) - Using interactions for A/B testing
* [Form Handling](/forms/lead-capture) - Advanced form interactions
* [Analytics Integration](/integrations/google-analytics) - Event tracking setup
* [Debug Window](/debugging/debug-window) - Testing and debugging interactions
* [Page Events](/funnels/page-events) - Funnel-level event tracking


# Internationalization (i18n)
Source: https://docs.elasticfunnels.io/pages/internationalization

Translate page copy with a brand-wide dictionary, switch the active language via URL, and render localized strings from templates and backend scripts.

ElasticFunnels gives you a single, brand-wide system for translating page
copy without forking pages or maintaining duplicate variants. You write
your page once, **reference translation keys in templates** (or backend
scripts), **store translations per language** in the admin, and the page
shows the right copy based on the visitor's language.

The system is intentionally narrow: it only translates copy. Layout,
images, links, and behavior stay identical across languages. Use
[Page Variants](./page-variants) when you need a fully different
experience per audience.

## How it works

There are two things to manage:

1. **Languages** — the list of locales your brand supports (e.g. `en`,
   `pt-br`, `de`). One language is your **default**.
2. **Entries** — for each language, a list of `key → translation` rows.
   The same key (e.g. `hero.title`) lives in every language.

Once a language has entries, any template or script that uses that key
under the **resolved** locale for the request will receive the matching
value.

### Translation keys

Keys use **dot notation** so you can group related copy together —
`hero.title`, `checkout.cta`, `faq.refund_policy`.

Use **letters, numbers, underscores, and dots** in keys (e.g. `hero.title`,
`form.email_placeholder`). The admin may allow a wider pattern for stored
keys; sticking to this subset keeps lookups predictable.

Each `key` is unique within a language but is meant to repeat across
languages — that's how the system knows the English `hero.title` and
the German `hero.title` are the same slot.

## Managing languages and translations

Open **Pages → Advanced → Translations** to manage everything in one
place.

### Add a language

1. Click **Add language**.
2. Enter a **locale code** — short BCP-47 tag like `en`, `de`, `pt-br`.
3. Optionally add a **display label** (shown only in the admin).
4. Toggle **Default language** for the language that should be served
   when no other language is selected.
5. Use **Sort order** to control the order in language pickers.

### Add translation entries

1. In the **Entries** section, pick a language from the dropdown.
2. Click **Add entry**.
3. Enter a **Key** (e.g. `hero.title`) and the translated **Value**.
4. Save.

Use the search box to filter by key or value when your dictionary grows.

### Bulk edit

Click **Bulk edit** above the entries table to switch to a
spreadsheet-style editor. Add or change many keys at once, then click
**Save all changes**. The whole batch saves together — if any row
fails validation, nothing is saved.

### Permissions

Access to translations is controlled by the **Translations** module
permissions in your role: `view`, `create`, `update`, `delete`.

## Choosing the active language

ElasticFunnels derives a **locale hint** from the request, then **snaps**
it to a language row configured for the brand (when any exist).

**Locale hint priority** (first match wins):

1. **Wildcard / route params** — `hl` or `locale` captured by a
   [wildcard route](/pages/wildcard-routes) (e.g. the slug `docs/{hl}`), also
   merged Express `params` when present. Note that a slug cannot *start* with a
   placeholder, so `/en/about` cannot be matched this way — use `?hl=en`.
2. **Query string** — `hl`, then `locale`, then `lang`.
3. **Session** — `session.locale`.
4. **Domain** — `locale` / `language` from domain config.
5. **Brand** — `locale` / `language` from brand variables.
6. **`Accept-Language`** — primary two-letter subtag of the first range
   (e.g. `en-US` → `en`).
7. **`en`** — final fallback for the hint.

**Snapping to brand languages** (when the brand has at least one language
in Advanced → Translations):

* If the hint matches a configured **code** exactly (after normalization),
  that language is used.
* Otherwise the brand **default** language is used, or the first language
  by sort order if no default is set.

There is **no** automatic `pt-br` → `pt` alias today: add both codes in
the admin if you need regional variants.

If the brand has **no** languages configured, the hint is still set on
the request for built-in helpers, but **`getTranslations()`** and
dictionary-backed **`t()`** / **`| t`** paths will not load entries from
the database.

### Clean URLs per language

If you want URLs like `/en/about` and `/pt-br/about` to switch the
active language, capture the locale segment in your page slug:

* **Page slug:** `{hl}/about`
* **URLs that match:** `/en/about`, `/pt-br/about`

The `{hl}` placeholder feeds into the route params used in step (1)
above.

## Using translations in templates

There are two sources of copy:

1. **Brand dictionary** (Advanced → Translations) — **`t()`**, **`| t`**,
   and **`getTranslations()`** use the **resolved** language for the request.
2. **Built-in product strings** (`src/locales` on the server) — used when
   **`t()`** or **`| t`** does not find a brand entry for the key; today the shipped
   catalog is **English**; extra locale files extend this over time.

```twig theme={null}
<h1>{{ t('title.greeting') }}</h1>
<h2>{{ 'hero.subtitle' | t }}</h2>
<img src="/hero.png" alt="{{ t('hero.alt') }}" />
<p>{{ dump(locales()) }}</p>
<p>Default: {{ defaultLocale() }}</p>
<p>{{ t('product.savings_percent', { percent: 20 }) }}</p>
<p>{{ 'product.savings_percent' | t:savingsOpts }}</p>
<p>Language: {{ getResolvedLanguage() }}</p>
<p>Active code (same as resolved): {{ locale }}</p>
```

| Function / filter | What it does |
| - | - |
| `getTranslations()` | Shallow copy of the full `key → value` map for the active resolved language. Async. |
| `getResolvedLanguage()` | Snapped language **code** from the brand configuration (e.g. `pt-br`). Async. |
| `t(key, params?)` | **Brand entry first** when the key exists for the resolved language; otherwise built-in JSON from `src/locales`. Optional `params` is an **object** for `{{ name }}`-style placeholders **only** for built-in strings. Async. |
| `expr \| t` and `expr \| t:params` | Same resolution as `t()`; `expr` yields the **key string** (often a quoted literal). Optional **`t:params`** passes an object for built-in **`{{ name }}`** interpolation — `params` must be a variable or safe expression on the page context, same rules as `t(key, params)`. Async. |
| `locales()` | Array of configured language codes for the brand (admin sort order). Async. |
| `defaultLocale()` | Default language code, or first by sort order, or `''`. Async. |

**`getTranslation(key)`** is still exposed for **brand-only** lookups (no built-in fallback, returns `''` if missing). For strings in pages and scripts, prefer **`t()`** or **`| t`** so product copy can fall through to the shipped catalog when useful.

Use **`{{ locale }}`** for the active resolved code on the page context, or **`getResolvedLanguage()`** inside expressions when you need the snapped code explicitly.

## Using translations in backend scripts

Backend scripts (`<script scope="backend">`) expose the same **brand**
helpers as templates (all async in the sandbox):

```javascript theme={null}
var code = await getResolvedLanguage();
var langs = await getLocales();
var def = await getDefaultLocale();
var hint = await getLocale();
var dict = await getTranslations();
var cta = await t('checkout.cta');
var title = await t('title.greeting');
```

**`t(key, params?)`** tries the **brand** dictionary first, then built-in
locale JSON (same as templates). Use `await`. **`getLocale()`** returns
the same resolved code as `{{ locale }}` (async in the sandbox).

There is **no** pipe-filter syntax in backend scripts — use **`await t('key')`**.

For the full host surface, see
[Backend Scripts → Data Functions](../backend-scripts/data-functions).

## Caching

Translations are served from a fast **in-memory cache** (per app
process). Saving languages or entries from the admin should **bust**
that cache via the worker (`brand_translation` or full `brand` clear) so
the next request reloads from the database.

## Patterns and pitfalls

* **Always set a default language** in Advanced → Translations so
  snapping has a predictable target when the URL hint does not match any
  row.
* **Use stable keys.** Renaming a key in the admin does not update your
  templates. Once `hero.title` exists, keep using it; rename only when
  the meaning of the slot truly changes.
* **Missing entries.** When the brand has no value for a key in the active
  language, **`t()` / `| t`** fall back to built-in strings when a catalog
  entry exists; otherwise prefer a sensible default in markup or a **`default:`**
  filter. **`getTranslation`** (brand-only) returns `''` when missing.
* **Exact language codes.** Add `pt` and `pt-br` separately if you need
  both; the runtime does not auto-collapse regions.

## Related

* [Wildcard routes](/pages/wildcard-routes) — capture an `hl` path segment
  (e.g. the slug `docs/{hl}`); the placeholder cannot be the first segment.
* [Page variables](./page-variables) — non-translation per-locale
  switches (currency formatting, date masks, etc.).
* [Backend scripts → data functions](../backend-scripts/data-functions)
  — backend reference for translation helpers.


# Order Tag
Source: https://docs.elasticfunnels.io/pages/order-tag

Display customer order history and details using the order tag system

The `<order>` tag allows you to display customer purchase history and order details on your pages. This is perfect for order confirmation pages, account pages, or any page where customers need to view their past purchases.

## Overview

The order tag system dynamically displays purchase conversions grouped by session. It automatically shows all orders associated with the current customer's email or session, making it easy to create personalized order history pages.

## Basic Usage

### Simple Order Display

```html theme={null}
<order>
  <h2>Order #{order_number}</h2>
  <p>Date: {order_date}</p>
  <p>Billing Address: {billing_address}</p>
  <p>Shipping Address: {shipping_address}</p>
</order>
```

### With Styling Attributes

You can add HTML attributes (like `class` or `id`) to the order tag:

```html theme={null}
<order class="order-card" id="order-history">
  <div class="order-header">
    <h3>Order #{order_number}</h3>
    <span class="order-date">{order_date}</span>
  </div>
  <div class="order-details">
    <p><strong>Billing:</strong> {billing_address}</p>
    <p><strong>Shipping:</strong> {shipping_address}</p>
  </div>
</order>
```

## Order Selection

The order tag automatically retrieves and displays orders based on the current customer session. Here's how orders are selected:

### Selection Criteria

1. **Customer Identification**: Orders are retrieved using:
   * The customer's email address (if available in session)
   * The current session ID (as a fallback)

2. **Order Type Filtering**: Only orders with `type="purchase"` are displayed. This ensures that:
   * Only actual purchases are shown (not leads, opt-ins, or other conversion types)
   * The order history is clean and relevant
   * Security is maintained by filtering out non-purchase conversions

3. **Grouping**: Orders are grouped by `session_id`, so multiple conversions from the same purchase session are displayed together as a single order.

### Sorting Orders

By default, orders are displayed with the **newest orders first**. You can control the sort order using the `sort-by` attribute:

```html theme={null}
<!-- Newest orders first (default) -->
<order sort-by="newest">
  <h3>Order #{order_number}</h3>
  <p>Date: {order_date}</p>
</order>

<!-- Oldest orders first -->
<order sort-by="oldest">
  <h3>Order #{order_number}</h3>
  <p>Date: {order_date}</p>
</order>
```

**Available sort options:**

* `sort-by="newest"` - Most recent orders first (default)
* `sort-by="oldest"` - Oldest orders first

### Limiting Orders

You can limit the number of orders displayed using the `limit` attribute:

```html theme={null}
<!-- Show only the 5 most recent orders -->
<order sort-by="newest" limit="5">
  <h3>Order #{order_number}</h3>
  <p>Date: {order_date}</p>
</order>

<!-- Show the 3 oldest orders -->
<order sort-by="oldest" limit="3">
  <h3>Order #{order_number}</h3>
  <p>Date: {order_date}</p>
</order>
```

**Limit behavior:**

* Must be a positive integer (1, 2, 3, etc.)
* If not specified, all orders are displayed
* Applied after sorting, so `limit="5"` with `sort-by="newest"` shows the 5 newest orders

### Combining Attributes

You can combine `sort-by` and `limit` with styling attributes:

```html theme={null}
<order class="recent-orders" sort-by="newest" limit="10">
  <div class="order-card">
    <h3>Order #{order_number}</h3>
    <p>Placed on {order_date}</p>
  </div>
</order>
```

## Security & Data Protection

The order tag system includes built-in security measures:

1. **Type Filtering**: Only `type="purchase"` conversions are displayed, preventing access to other conversion types
2. **Input Validation**: All attributes are validated and sanitized:
   * `sort-by` only accepts `"newest"` or `"oldest"` (case-insensitive)
   * `limit` must be a positive integer
   * Invalid values are ignored and defaults are used
3. **Attribute Escaping**: All attribute values are properly escaped to prevent injection attacks
4. **Session-Based Access**: Orders are only shown to customers with valid sessions (email or customer flag)

## Order-Level Placeholders

These placeholders work within the `<order>` tag to display order information:

### `{order_date}`

Displays the formatted order date and time.

* **Format**: "Month Day, Year, Hour:Minute AM/PM"
* **Example**: "January 15, 2024, 2:30 PM"

```html theme={null}
<order>
  <p>Order placed on {order_date}</p>
</order>
```

### `{order_number}`

Shows the public order ID for the purchase.

```html theme={null}
<order>
  <p>Order Number: {order_number}</p>
</order>
```

### `{billing_address}`

Displays the complete billing address (address, city, state, zip).

```html theme={null}
<order>
  <div>
    <strong>Billing Address:</strong>
    <p>{billing_address}</p>
  </div>
</order>
```

### `{shipping_address}`

Displays the complete shipping address (address, city, state, zip).

```html theme={null}
<order>
  <div>
    <strong>Shipping Address:</strong>
    <p>{shipping_address}</p>
  </div>
</order>
```

### `{order_status_text}`

Order status text (currently empty, reserved for future use).

### `{charge_code}`

Charge code information (currently empty, reserved for future use).

### `{customer_name}`

Customer name placeholder. This works both inside and outside the order tag.

```html theme={null}
<h1>Welcome, {customer_name}!</h1>
<order>
  <p>Your order history:</p>
</order>
```

**Note**: If there's no customer session or no orders, `{customer_name}` will be removed from the page. Use `,{customer_name}` if you want the comma removed when the name is empty (e.g., "Hello, " becomes "Hello" if no customer).

## Nested Tags

### Order Products

Use `<order-product>` to display individual products in an order. This tag automatically loops through all non-bonus products in the order.

```html theme={null}
<order>
  <h3>Order #{order_number}</h3>
  <div class="products">
    <order-product class="product-item">
      <img src="{product_image_url}" alt="{product_name}">
      <h4>{product_name}</h4>
      <p class="price">{price}</p>
    </order-product>
  </div>
</order>
```

#### Order Product Placeholders

* **`{product_image_url}`**: URL of the product image
* **`{product_name}`**: Name of the product
* **`{price}`**: Formatted price with currency symbol (e.g., "\$97.00")

### Bonus Products

Use `<order-bonus-product>` to display bonus products included with the order. Each bonus product is shown only once, even if it appears multiple times in the order.

```html theme={null}
<order>
  <h3>Order #{order_number}</h3>
  
  <div class="bonus-products">
    <h4>Bonus Items Included:</h4>
    <order-bonus-product class="bonus-item">
      <img src="{bonus_product_image_url}" alt="{bonus_product_name}">
      <h5>{bonus_product_name}</h5>
      <a href="{bonus_download}" download>Download</a>
    </order-bonus-product>
  </div>
</order>
```

#### Bonus Product Placeholders

* **`{bonus_product_image_url}`**: URL of the bonus product image
* **`{bonus_product_name}`**: Name of the bonus product
* **`{bonus_download}`**: Download link/file for the bonus product

### Order Product Tracking

The `<order-product-tracking>` tag is reserved for future tracking functionality. Currently, it returns empty content.

```html theme={null}
<order>
  <order-product-tracking>
    <!-- Tracking information will be available in future updates -->
  </order-product-tracking>
</order>
```

## Complete Example

Here's a complete example of an order history page:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Order History</title>
  <style>
    .order-container {
      border: 1px solid #ddd;
      padding: 20px;
      margin-bottom: 20px;
      border-radius: 8px;
    }
    .product-item {
      display: flex;
      gap: 15px;
      padding: 15px;
      border-bottom: 1px solid #eee;
    }
    .product-item img {
      width: 80px;
      height: 80px;
      object-fit: cover;
    }
    .bonus-item {
      background: #f0f9ff;
      padding: 10px;
      margin: 5px 0;
      border-radius: 4px;
    }
  </style>
</head>
<body>
  <h1>Welcome, {customer_name}!</h1>
  <h2>Your Order History</h2>
  
  <order class="order-container">
    <div class="order-header">
      <h3>Order #{order_number}</h3>
      <p class="order-date">Placed on {order_date}</p>
    </div>
    
    <div class="order-addresses">
      <div>
        <strong>Billing Address:</strong>
        <p>{billing_address}</p>
      </div>
      <div>
        <strong>Shipping Address:</strong>
        <p>{shipping_address}</p>
      </div>
    </div>
    
    <div class="order-products">
      <h4>Products:</h4>
      <order-product class="product-item">
        <img src="{product_image_url}" alt="{product_name}">
        <div>
          <h5>{product_name}</h5>
          <p class="price">{price}</p>
        </div>
      </order-product>
    </div>
    
    <div class="bonus-section">
      <h4>Bonus Items:</h4>
      <order-bonus-product class="bonus-item">
        <img src="{bonus_product_image_url}" alt="{bonus_product_name}" style="width: 50px; height: 50px;">
        <div>
          <strong>{bonus_product_name}</strong>
          <br>
          <a href="{bonus_download}" download>Download Bonus</a>
        </div>
      </order-bonus-product>
    </div>
  </order>
</body>
</html>
```

## How It Works

1. **Customer Detection**: The system checks if the visitor has a customer session (email or customer flag).

2. **Order Retrieval**: If a customer session exists, the system retrieves all conversions associated with:
   * The customer's email address (primary method)
   * The current session ID (fallback method)

3. **Order Filtering**: Only conversions with `type="purchase"` are included. This ensures:
   * Only actual purchases are displayed
   * Other conversion types (leads, opt-ins, etc.) are excluded
   * Security is maintained

4. **Order Sorting**: Orders are sorted based on the `sort-by` attribute:
   * `"newest"` (default): Most recent orders first
   * `"oldest"`: Oldest orders first
   * Sorting is based on the `created_at` timestamp

5. **Order Limiting**: If a `limit` attribute is specified, only that many orders are displayed (after sorting).

6. **Order Grouping**: Orders are grouped by `session_id`, so multiple conversions from the same purchase session are displayed together as a single order.

7. **Tag Processing**:
   * The `<order>` tag is replaced with HTML for each order group
   * Nested tags (`<order-product>`, `<order-bonus-product>`) are processed within each order
   * All placeholders are replaced with actual order data
   * Attributes are validated and sanitized for security

8. **Empty State**: If no customer session exists or no orders are found:
   * The entire `<order>` tag is removed from the page
   * `{customer_name}` placeholders are removed
   * The page displays without order information

## Important Notes

### Customer Session Required

The order tag only displays content when:

* The visitor has a customer email in their session, OR
* The visitor has the `is_customer` flag set in their session

If neither condition is met, the order tag and customer name placeholders are removed from the page.

### Order Type Restriction

**Only purchase orders are displayed.** The system automatically filters to show only conversions with `type="purchase"`. This means:

* Leads, opt-ins, and other conversion types are never shown
* Only actual completed purchases appear in order history
* This is a security feature that cannot be overridden

### Multiple Orders

If a customer has multiple orders (from different sessions), each order group will be displayed as a separate `<order>` block. The system automatically handles multiple orders and can sort/limit them as needed.

### Sorting Behavior

* **Default**: Orders are sorted newest first
* **Per-Tag**: Each `<order>` tag can have its own `sort-by` and `limit` attributes
* **Group Sorting**: Orders are sorted by the first conversion's `created_at` date within each session group

### Styling

You can style order tags using CSS classes or IDs:

```html theme={null}
<order class="my-order-card" sort-by="newest" limit="5">
  <!-- Order content -->
</order>
```

The attributes you add to the `<order>` tag (except `sort-by` and `limit`) are applied to the wrapper `<div>` that contains each order.

## Best Practices

1. **Always include order number**: Use `{order_number}` so customers can reference their orders
2. **Show order date**: Display `{order_date}` to help customers identify when they made purchases
3. **Organize products clearly**: Use proper HTML structure and CSS to make product lists readable
4. **Handle empty states**: Design your page to look good even when no orders are present
5. **Mobile responsive**: Ensure your order display works well on mobile devices
6. **Test with multiple orders**: Verify that multiple orders display correctly

## Troubleshooting

### Orders Not Showing

* **Check customer session**: Ensure the visitor is logged in or has a customer session
* **Verify purchases**: Confirm that purchase conversions exist for the customer
* **Check order type**: Only "purchase" type conversions are displayed

### Customer Name Not Appearing

* The `{customer_name}` placeholder requires at least one order to exist
* If no orders exist, the placeholder is removed from the page
* Use `,{customer_name}` if you want the comma removed when the name is empty

### Products Not Displaying

* Ensure products are associated with the order conversions
* Check that products are not marked as bonus products (use `<order-bonus-product>` for those)
* Verify product data exists in the system


# Pages Overview
Source: https://docs.elasticfunnels.io/pages/overview

Create, edit, test, and publish pages in ElasticFunnels

Pages are the building blocks of your funnels. They are where visitors land, read your offer, buy, opt in, or move to the next step.

## What Are Pages?

Pages are individual web pages that make up your funnels. Each page can be:

* **Landing pages** - Entry points for your marketing campaigns
* **Sales pages** - Product presentations and offers
* **Thank you pages** - Post-purchase or post-signup confirmations
* **Order history pages** - Customer account pages showing past purchases
* **Upsell pages** - Additional offers after initial purchase

## Core Concepts

### Page Types

From **Create Page**, choose the starting point that fits the job:

1. **AI Page Builder** - Describe what you need; the app generates a draft you refine in the builder (beta).
2. **AI Page Cloner** - Import a public URL into an editable page when your plan includes it.
3. **Arbitrage Page Builder** - Guided flow tuned for arbitrage-style landers.
4. **Drag and Drop Builder** - Page details, then the visual canvas.
5. **Choose Template** - Pick from the template library, then finish the prompts.
6. **Checkout Page** - Shown only when payments are set up; checkout-oriented templates (Stripe, NMI, PayPal, Klarna, and similar).
7. **Code Editor** - Page details, then HTML, CSS, and JavaScript.

For the full Create Page walkthrough, see [Create Landing Page](/pages/create-landing-page).

### Page Variants

Create multiple versions of the same page for split testing and optimization. Each variant can have different content, layouts, or functionality while sharing the same URL structure.

### Dynamic Content

Pages support dynamic content that changes based on:

* Visitor status (whitelisted vs non-whitelisted)
* Device type (mobile, tablet, desktop)
* Query parameters
* Customer data
* Purchase history

## Getting Started

### Create Your First Page

1. Open **Pages** in the sidebar.
2. Click **Create Page**. Choose AI, a template, drag-and-drop, code, or checkout when your brand supports it.
3. Pick the card that matches how you want to work.
4. Complete **page details**, template questions, or the AI flow the app shows for that path.
5. Build in the builder or editor, preview, then publish or leave the page on draft.

<CardGroup>
  <Card title="Create Landing Page" icon="file-plus" href="/pages/create-landing-page">
    Choose AI, templates, drag-and-drop, code, or checkout when your brand supports it
  </Card>

  <Card title="Page Variants" icon="layers" href="/pages/page-variants">
    Create and manage multiple versions of your pages for split testing
  </Card>

  <Card title="Page Revisions" icon="clock-rotate-left" href="/pages/page-revisions">
    Understand how revisions protect your work and restore previous versions
  </Card>
</CardGroup>

## Page Features

### Containers

Containers are specialized page elements that add dynamic behavior:

* **CTA Container** - Reveals content when triggered (e.g., after VSL)
* **Hide on CTA Container** - Hides content when CTA is triggered
* **Merchant Container** - Shows merchant-specific content
* **Split Test Container** - A/B test different content variations
* **Lazy Load Container** - Defers loading until visitor scrolls
* **Whitelisted/Non-Whitelisted Containers** - Show different content based on visitor status

<Card title="Containers" icon="box" href="/pages/containers">
  Use containers for dynamic content display
</Card>

### Interactions

Add interactive behaviors to any page element:

* **Click handlers** - Execute JavaScript, show modals, track events
* **Hover effects** - Tooltips, previews, animations
* **Form interactions** - Validation, success/error handling
* **Animations** - Slide, fade, scale, rotate effects
* **Device-specific behavior** - Different interactions for mobile/desktop

<Card title="Interactions Panel" icon="cursor-click" href="/pages/interactions-panel">
  Add interactive behaviors to your page elements with clicks, hovers, and custom JavaScript
</Card>

### Content Visibility Control

Control which visitors can see specific content:

* **Whitelisted visitors** - See full content (VSL, sales pages)
* **Non-whitelisted visitors** - See standard content (TSL, basic info)
* **Query parameter whitelisting** - Whitelist via URL parameters
* **Domain-level whitelisting** - Auto-whitelist all visitors to a domain
* **Hide content from competition** - Protect sensitive information from competitors

<Card title="Content Visibility Control" icon="eye" href="/pages/visitor-based-content">
  Control which visitors can see specific content based on whitelisting status
</Card>

### Order Tags

Display customer order history and purchase details:

* **Order information** - Date, order number, addresses
* **Product listings** - All products in each order
* **Bonus products** - Included bonus items with download links
* **Customer personalization** - Show customer name and order history

<Card title="Order Tag" icon="shopping-cart" href="/pages/order-tag">
  Display customer order history and details using the order tag system
</Card>

### Product & Collection Tags

Display dynamic product listings and collection content:

* **Product Item Tag** - Filter and display products by type, classification, or codes
* **Collection Item Tag** - Display entries from reusable collections (testimonials, FAQs, etc.)

<CardGroup>
  <Card title="Product Item Tag" icon="package" href="/pages/product-item-tag">
    Display dynamic product listings filtered by type, classification, or codes
  </Card>

  <Card title="Collection Item Tag" icon="database" href="/pages/collection-item-tag">
    Display dynamic content from collections using templates
  </Card>
</CardGroup>

### Page Variables & Placeholders

Use dynamic variables to personalize your pages:

* **Date variables** - Current date, day, month, year, hour
* **Customer variables** - Name, email, address, order history
* **Query parameters** - Access URL parameters for tracking and personalization

<Card title="Page Variables" icon="code" href="/pages/page-variables">
  Use dynamic variables and placeholders to personalize your pages
</Card>

## Page Management

### Organizing Pages

* **Domain assignment** - Assign pages to specific domains
* **Page status** - Draft, published, or archived
* **[Revision history](/pages/page-revisions)** - Track changes and revert if needed
* **Page templates** - Save and reuse page designs

### Performance Optimization

* **Lazy loading** - Defer loading of below-fold content
* **Image optimization** - Compress and optimize images
* **Mobile optimization** - Ensure pages work on all devices
* **Loading speed** - Monitor and improve page load times

## Advanced Features

### Dynamic Content

Pages can display content that changes based on:

* Customer purchase history
* Query parameters
* Visitor whitelisting status
* Device type
* Time of day
* Geographic location

### Integration with Funnels

Pages connect inside funnels:

* **Funnel nodes** - Connect pages in your funnel flow
* **Split testing** - Test different page variants
* **Page events** - Trigger actions based on page interactions
* **Analytics** - Track page performance and conversions

## Best Practices

### Design Principles

1. **Clear call-to-action** - Make it obvious what visitors should do
2. **Mobile-first** - Design for mobile, enhance for desktop
3. **Fast loading** - Optimize images and minimize resources
4. **Trust signals** - Include testimonials, guarantees, security badges
5. **Focused messaging** - One clear goal per page

### Content Strategy

1. **Compelling headlines** - Grab attention immediately
2. **Benefit-focused copy** - Focus on what visitors gain
3. **Social proof** - Testimonials, reviews, case studies
4. **Visual hierarchy** - Guide the eye to important elements
5. **Progressive disclosure** - Reveal information gradually

### Technical Considerations

1. **Test thoroughly** - Preview on multiple devices and browsers
2. **Monitor performance** - Track loading speed and user engagement
3. **Update regularly** - Keep content fresh and relevant
4. **Backup before changes** - Save versions before major updates
5. **Document your setup** - Note any special configurations

## Common Use Cases

### Landing Pages

Create high-converting landing pages for your marketing campaigns:

* Lead capture forms
* Product presentations
* Event registrations
* Newsletter signups

### Sales Pages

Build persuasive sales pages that convert:

* Video sales letters (VSL)
* Long-form sales copy
* Product demonstrations
* Pricing tables

### Thank You Pages

Design post-action confirmation pages:

* Order confirmations
* Download pages
* Upsell offers
* Social sharing prompts

### Account Pages

Create customer-facing account pages:

* Order history
* Account settings
* Download libraries
* Support information

## Troubleshooting

### Common Issues

* **Pages not loading** - Check domain settings and page status
* **Content not displaying** - Verify container settings and conditions
* **Interactions not working** - Check browser console for errors
* **Mobile issues** - Test responsive design and device-specific settings

### Getting Help

If you encounter issues:

1. **Check documentation** - Review relevant guides
2. **Preview mode** - Test changes before publishing
3. **Browser console** - Look for JavaScript errors
4. **Contact support** - Reach out for assistance

## Related Documentation

* [Funnels](/funnels/create-funnel) - Connect pages into complete funnels
* [Page Events](/funnels/page-events) - Add dynamic behavior to pages
* [Split Testing](/funnels/split-testing) - Test different page versions
* [Products](/products/buy-links) - Add purchase links to pages
* [Forms](/forms/lead-capture) - Create lead capture forms
* [Analytics](/analytics/conversions) - Track page performance

## Quick Links

<CardGroup>
  <Card title="Create Landing Page" href="/pages/create-landing-page" />

  <Card title="Page Variants" href="/pages/page-variants" />

  <Card title="Page Revisions" href="/pages/page-revisions" />

  <Card title="Containers" href="/pages/containers" />

  <Card title="Interactions Panel" href="/pages/interactions-panel" />

  <Card title="Content Visibility Control" href="/pages/visitor-based-content" />

  <Card title="Order Tag" href="/pages/order-tag" />

  <Card title="Product Item Tag" href="/pages/product-item-tag" />

  <Card title="Collection Item Tag" href="/pages/collection-item-tag" />

  <Card title="Page Variables" href="/pages/page-variables" />
</CardGroup>


# Page Revisions
Source: https://docs.elasticfunnels.io/pages/page-revisions

Your work is automatically saved so you can restore previous versions anytime

Page revisions automatically save your work as you edit, so you never lose your changes. You can view your revision history and restore any previous version at any time.

## How It Works

**Your work is protected automatically.** Here's what happens behind the scenes:

* **While you edit** - Your changes are saved as a draft, separate from your live page
* **When you publish** - A backup of your previous version is saved before the new one goes live
* **Your history is kept** - All your saved versions are preserved so you can go back anytime

<Note>
  Visitors always see your published page. Your drafts and edits are private until you choose to publish.
</Note>

## Viewing Your Revision History

To see previous versions of your page:

1. Open your page in the builder
2. Click **"Revisions"** or the history icon
3. Browse your saved versions by date
4. Click any revision to preview it

## Restoring a Previous Version

Found a version you want to bring back? You have two options:

### Replace Your Current Page

Use this when you want to undo recent changes:

1. Select the revision you want
2. Click **"Restore to Current"**
3. Review the restored content in the builder
4. Publish when you're ready

<Warning>
  This will replace your current draft. Save any work you want to keep before restoring.
</Warning>

### Create a New Page from a Revision

Use this when you want to keep your current page and also use an older version:

1. Select the revision you want
2. Click **"Restore to New Page"**
3. Give the new page a name
4. Edit and publish independently

This is great for:

* Recovering content you deleted
* Creating a variant based on an older design
* Comparing different versions side by side

## What Gets Saved

Every revision captures your complete page:

* All your content and text
* Styling and layout
* Any interactions or animations you've added
* Page settings and configuration

<Note>
  Images and videos are stored separately. If you delete media from your library, it may affect how older revisions display.
</Note>

## Discarding Your Draft

Changed your mind about recent edits? You can discard your draft to go back to the published version:

1. Click **"Discard Changes"** or **"Discard Draft"**
2. Confirm the action
3. Your page returns to the last published version

Your revision history and published page stay intact—only the current draft is removed.

## Tips for Working with Revisions

* **Save often** - Your work is auto-saved, but clicking save ensures nothing is lost
* **Publish when ready** - Don't leave important changes sitting in draft too long
* **Check history before big changes** - Know what version you can restore to if needed
* **Use "Restore to New Page"** for experiments - Keep your original safe while trying new ideas

## Troubleshooting

### My changes aren't saving

* Check your internet connection
* Look for any error messages
* Try clicking the save button manually
* Refresh the page and try again

### I can't find a revision I'm looking for

* Make sure you're viewing the correct page
* Check if you're looking at the right variant (each variant has its own history)
* Revisions are listed by date—scroll through the list

### A restored revision looks different than expected

* Images may have been updated or removed since that version was saved
* External fonts or resources may have changed
* Try previewing in the same browser you originally used

## Related

<CardGroup>
  <Card title="Page Variants" icon="layers" href="/pages/page-variants">
    Create multiple versions of your page for split testing
  </Card>

  <Card title="Pages Overview" icon="file" href="/pages/overview">
    Create, edit, test, and publish pages
  </Card>
</CardGroup>


# Page Variables & Placeholders
Source: https://docs.elasticfunnels.io/pages/page-variables

Use dynamic variables and placeholders to personalize your pages with customer data, dates, query parameters, and more

Page variables and placeholders allow you to dynamically insert content into your pages. They're automatically replaced with actual values when the page is rendered, making it easy to personalize content for each visitor.

## Variable Formats

Use **double curly braces** for variables:

* **Template format**: `{{ variable.path }}` — Use a path to the value (e.g. `{{ query.campaign }}`, `{{ customer.name }}`).

This format works in HTML content and in JavaScript code. Date and time placeholders use the percent format (e.g. `%DAY_NAME%`, `%YEAR%`) as shown in the Date Variables section below.

## Date Variables

Display current date and time information using these placeholders:

### `%DAY_NAME%`

Full name of the day of the week.

**Example**: "Monday", "Tuesday", "Wednesday"

```html theme={null}
<p>Today is %DAY_NAME%</p>
<!-- Output: Today is Monday -->
```

### `%DAY%`

Day of the month (1-31).

**Example**: 1, 15, 31

```html theme={null}
<p>Today is the %DAY%</p>
<!-- Output: Today is the 15 -->
```

### `%DAY_POSTFIX%`

Ordinal suffix for the day (st, nd, rd, th).

**Example**: "st", "nd", "rd", "th"

```html theme={null}
<p>Today is the %DAY%%DAY_POSTFIX%</p>
<!-- Output: Today is the 15th -->
```

### `%MONTH_NAME%`

Full name of the month.

**Example**: "January", "February", "March"

```html theme={null}
<p>It's %MONTH_NAME%</p>
<!-- Output: It's January -->
```

### `%MONTH%`

Month number (0-11, where 0 = January).

**Example**: 0, 5, 11

```html theme={null}
<p>Month number: %MONTH%</p>
<!-- Output: Month number: 0 -->
```

### `%YEAR%`

Full 4-digit year.

**Example**: 2024, 2025

```html theme={null}
<p>Copyright %YEAR%</p>
<!-- Output: Copyright 2024 -->
```

### `%HOUR%`

Current hour in 24-hour format (0-23).

**Example**: 0, 14, 23

```html theme={null}
<p>Current hour: %HOUR%</p>
<!-- Output: Current hour: 14 -->
```

### Complete Date Example

```html theme={null}
<div class="date-display">
  <p>Today is %DAY_NAME%, %MONTH_NAME% %DAY%%DAY_POSTFIX%, %YEAR%</p>
  <p>Current time: %HOUR%:00</p>
</div>
<!-- Output: Today is Monday, January 15th, 2024 -->
<!-- Output: Current time: 14:00 -->
```

## Customer Variables

Display customer information when a customer session exists.

### `%CUSTOMER_FNAME%`

Customer's first name from session.

```html theme={null}
<p>Hello, %CUSTOMER_FNAME%!</p>
<!-- Output: Hello, John! -->
```

### `%CUSTOMER_FNAME%,`

Customer's first name with a trailing comma. The comma is removed if no first name is available.

```html theme={null}
<p>Welcome%CUSTOMER_FNAME%, to our store!</p>
<!-- With name: Welcome John, to our store! -->
<!-- Without name: Welcome to our store! -->
```

### `{{ customer_name }}`

Customer's full name. Works in both HTML and JavaScript.

```html theme={null}
<h1>Welcome, {{ customer_name }}!</h1>

<script>
  console.log('Customer: {{ customer_name }}');
</script>
```

**Note**: This variable is populated from order data. If no orders exist, it will be empty.

### `{{ customer.* }}` Variables

Access detailed customer information using the `{{ customer.* }}` format. These variables are populated from the customer's most recent conversion/purchase.

**Personal Information:**

* `{{ customer.email }}` - Customer email address
* `{{ customer.name }}` - Full name
* `{{ customer.first_name }}` - First name
* `{{ customer.last_name }}` - Last name
* `{{ customer.phone }}` - Phone number
* `{{ customer.country }}` - Country

**Address Information:**

* `{{ customer.address }}` - Street address
* `{{ customer.city }}` - City
* `{{ customer.state }}` - State/Province
* `{{ customer.zip }}` - ZIP/Postal code

**Billing Information:**

* `{{ customer.billing_address }}` - Billing street address
* `{{ customer.billing_city }}` - Billing city
* `{{ customer.billing_state }}` - Billing state
* `{{ customer.billing_zip }}` - Billing ZIP code
* `{{ customer.billing_country }}` - Billing country

**Shipping Information:**

* `{{ customer.shipping_address }}` - Shipping street address
* `{{ customer.shipping_city }}` - Shipping city
* `{{ customer.shipping_state }}` - Shipping state
* `{{ customer.shipping_zip }}` - Shipping ZIP code
* `{{ customer.shipping_country }}` - Shipping country

**Order History:**

* `{{ customer.total_orders }}` - Total number of orders
* `{{ customer.last_order_date }}` - Date of most recent order
* `{{ customer.last_order_total }}` - Total amount of most recent order
* `{{ customer.last_order_currency }}` - Currency of most recent order
* `{{ customer.order_ids }}` - Comma-separated list of order IDs

**Special Variables:**

* `{{ customer.email_hashed }}` - SHA-256 hashed email (for privacy/analytics)

### Customer Variable Examples

```html theme={null}
<!-- Personalization -->
<h1>Welcome back, {{ customer.first_name }}!</h1>
<p>Your email: {{ customer.email }}</p>

<!-- Address display -->
<div class="shipping-info">
  <p>{{ customer.shipping_address }}</p>
  <p>{{ customer.shipping_city }}, {{ customer.shipping_state }} {{ customer.shipping_zip }}</p>
</div>

<!-- Order history -->
<p>You have {{ customer.total_orders }} order(s)</p>
<p>Last order: {{ customer.last_order_date }}</p>

<!-- In JavaScript -->
<script>
  const customerEmail = '{{ customer.email }}';
  const orderCount = '{{ customer.total_orders }}';
</script>
```

**Important Notes:**

* Customer variables require a valid customer session (email or `is_customer` flag)
* If no session exists, customer variables are removed from the page
* Variables are populated from the most recent conversion/purchase
* Empty values are replaced with empty strings

## Brand & System Variables

Display brand information and system-level data that's available on all pages.

### `{{ brand_name }}`

Your brand/company name.

```html theme={null}
<h1>Welcome to {{ brand_name }}</h1>
<!-- Output: Welcome to My Company -->

<footer>
  <p>{{ brand_name }} - All rights reserved</p>
</footer>
```

### `{{ domain }}`

Current domain name.

```html theme={null}
<p>Visit us at {{ domain }}</p>
<!-- Output: Visit us at example.com -->

<a href="https://{{ domain }}">Home</a>
<!-- Output: <a href="https://example.com">Home</a> -->
```

### `{{ click_id }}`

Click tracking ID for the current session.

```html theme={null}
<!-- Pass click ID to tracking -->
<script>
  const clickId = '{{ click_id }}';
  // Use for analytics or tracking
</script>

<!-- In URLs -->
<a href="/checkout?c={{ click_id }}">Buy Now</a>
```

### IP & Location Variables

Access visitor IP address and location information (when available).

#### `{{ ip_whois.ip }}`

Visitor's IP address.

```html theme={null}
<!-- Display IP (usually for debugging) -->
<p>Your IP: {{ ip_whois.ip }}</p>
```

#### `{{ ip_whois.country }}`

Visitor's country based on IP geolocation.

```html theme={null}
<p>Country: {{ ip_whois.country }}</p>
<!-- Output: Country: United States -->
```

#### `{{ ip_whois.city }}`

Visitor's city based on IP geolocation.

```html theme={null}
<p>City: {{ ip_whois.city }}</p>
<!-- Output: City: New York -->
```

#### `{{ ip_whois.region }}`

Visitor's region/state based on IP geolocation.

```html theme={null}
<p>Region: {{ ip_whois.region }}</p>
<!-- Output: Region: New York -->
```

**Important Notes:**

* IP geolocation data is approximate and may not be 100% accurate
* Location data is only available when `{{ ip_whois.* }}` variables are used in the page
* IP address is always available, but country/city/region require geolocation lookup
* Use these variables responsibly and in compliance with privacy regulations

### Custom Brand Variables (`{{ var.* }}`)

Access custom variables defined in your brand settings using dot notation.

**Format**: `{{ var.path.to.variable }}`

**Default Values**: `{{ var.path.to.variable=default_value }}`

Custom brand variables are defined in your brand settings as JSON. You can access nested values using dot notation.

**Example Brand Variables JSON:**

```json theme={null}
{
  "company": {
    "name": "My Company",
    "phone": "1-800-123-4567",
    "email": "support@example.com"
  },
  "social": {
    "facebook": "https://facebook.com/mycompany",
    "twitter": "https://twitter.com/mycompany"
  },
  "settings": {
    "shipping_days": 5,
    "return_policy": "30 days"
  }
}
```

**Usage Examples:**

```html theme={null}
<!-- Access nested values -->
<p>Company: {{ var.company.name }}</p>
<!-- Output: Company: My Company -->

<p>Phone: {{ var.company.phone }}</p>
<!-- Output: Phone: 1-800-123-4567 -->

<a href="{{ var.social.facebook }}">Facebook</a>
<!-- Output: <a href="https://facebook.com/mycompany">Facebook</a> -->

<p>Shipping: {{ var.settings.shipping_days }} days</p>
<!-- Output: Shipping: 5 days -->
```

**Default Values:**

If a variable doesn't exist, you can provide a default value:

```html theme={null}
<!-- Use default if variable doesn't exist -->
<p>Phone: {{ var.company.phone=Not available }}</p>
<!-- If var.company.phone exists: Phone: 1-800-123-4567 -->
<!-- If it doesn't exist: Phone: Not available -->

<p>Support: {{ var.support.email=support@example.com }}</p>
```

**Important Notes:**

* Custom variables are defined in your brand settings
* Use dot notation to access nested values
* Variables work in HTML, head HTML, and JavaScript
* If a variable doesn't exist and no default is provided, you'll see: `<ef-undefined>undefined: var.path</ef-undefined>`
* Default values are only used when the variable is undefined

### Brand Variable Examples

```html theme={null}
<!-- Footer with brand info -->
<footer>
  <div class="company-info">
    <h3>{{ brand_name }}</h3>
    <p>Domain: {{ domain }}</p>
    <p>Phone: {{ var.company.phone }}</p>
    <p>Email: {{ var.company.email }}</p>
  </div>
  
  <div class="social-links">
    <a href="{{ var.social.facebook }}">Facebook</a>
    <a href="{{ var.social.twitter }}">Twitter</a>
  </div>
  
  <p>© {{ brand_name }} %YEAR%</p>
</footer>

<!-- Tracking with click ID -->
<script>
  // Track page view
  gtag('event', 'page_view', {
    'click_id': '{{ click_id }}',
    'domain': '{{ domain }}',
    'brand': '{{ brand_name }}'
  });
</script>
```

## Query Parameter Variables

Access URL query parameters to personalize content based on traffic source, campaigns, or other URL data.

### `{{ query.* }}`

Access any query parameter from the URL.

**Format**: `{{ query.parameter_name }}`

**Example URL**: `https://yoursite.com/page?aff_id=123&source=facebook`

```html theme={null}
<p>Affiliate ID: {{ query.aff_id }}</p>
<!-- Output: Affiliate ID: 123 -->

<p>Source: {{ query.source }}</p>
<!-- Output: Source: facebook -->
```

### `{{ queryparams }}`

Get the complete query string for use in URLs.

```html theme={null}
<a href="/checkout?{{ queryparams }}">Checkout</a>
<!-- Output: <a href="/checkout?aff_id=123&source=facebook">Checkout</a> -->
```

### Query Parameter Examples

```html theme={null}
<!-- Track affiliate -->
<p>Referred by: {{ query.aff_id }}</p>

<!-- Campaign tracking -->
<div data-campaign="{{ query.utm_campaign }}">
  Campaign content
</div>

<!-- Pass parameters to checkout -->
<a href="/checkout?{{ queryparams }}">Buy Now</a>

<!-- Conditional content based on parameter -->
<script>
  const source = '{{ query.source }}';
  if (source === 'email') {
    // Show email-specific content
  }
</script>
```

**Important Notes:**

* Query parameters are case-sensitive
* If a parameter doesn't exist, the variable is replaced with an empty string
* All query parameter values are automatically escaped for security
* Unused query parameter variables are cleaned up automatically

## Request & device context

Request and device fields are available in the **backend template engine** (server-side). They use the same data as [Script Rule](/funnels/script-rule), so you can show or hide content by device, customer status, referrer, and merchant.

Use **`request.*`** in conditions and output, or **`is_mobile`** / **`is_tablet`** at the top level (same names as in script rules).

### In template conditionals (`@if`)

```html theme={null}
@if(request.is_mobile)
  <p>You're on mobile — tap here to buy.</p>
@endif

@if(request.is_mobile)
  <!-- mobile -->
  <div class="mobile-cta">Tap to buy</div>
@else
  <!-- desktop -->
  <div class="desktop-cta">Click to buy</div>
@endif

@if(is_mobile && !is_tablet)
  <p>Phone-only offer.</p>
@endif

@if(request.is_customer)
  <p>Welcome back!</p>
@endif
```

### In output (`{{ }}`)

```html theme={null}
<p>Device: {{ request.device.type }}</p>
<p>Mobile: {{ request.is_mobile }}</p>
<p>Referrer: {{ request.referrer }}</p>
```

### Available request fields

| Variable | Type | Description |
| - | - | - |
| `request.is_mobile` | Boolean | Visitor is on a mobile device |
| `request.is_tablet` | Boolean | Visitor is on a tablet |
| `request.device` | Object | Device info: `type`, `user_agent`, `vendor`, `model`, `os`, `browser` (name/version) |
| `request.query` | Object | URL query parameters (same as `{{ query.* }}`) |
| `request.is_customer` | Boolean | Visitor has made a purchase |
| `request.referer` / `request.referrer` | String | Referrer URL |
| `request.merchant_code` | String | Active payment processor code (e.g. `buygoods`, `stripe`) |

### Top-level parity with script rules

For the same naming as in [Script Rule](/funnels/script-rule), **`is_mobile`** and **`is_tablet`** are also available at the top level (no `request.` prefix):

```html theme={null}
@if(is_mobile)
  <div class="mobile-cta">...</div>
@endif
```

## Variable Usage Tips

### Combining Variables

You can combine multiple variables for rich personalization:

```html theme={null}
<p>Hello %CUSTOMER_FNAME%, today is %DAY_NAME%, %MONTH_NAME% %DAY%%DAY_POSTFIX%</p>
<!-- Output: Hello John, today is Monday, January 15th -->
```

### Conditional Display

Use variables with CSS or JavaScript for conditional display:

```html theme={null}
<!-- Hide if no customer name -->
<div id="welcome" style="display: {{ customer.name ? 'block' : 'none' }}">
  Welcome, {{ customer.name }}!
</div>

<!-- JavaScript conditional -->
<script>
  if ('{{ customer.email }}') {
    console.log('Customer logged in');
  }
</script>
```

### Security Considerations

* All variable values are automatically escaped to prevent XSS attacks
* Customer data is only shown to authenticated customers
* Query parameters are sanitized before use
* Empty variables are safely removed

### Performance

* Variables are replaced server-side during page rendering
* No client-side processing required
* Variables that don't exist are efficiently removed

## Troubleshooting

### Variables Not Showing

**Issue**: Variable appears as literal text (e.g., `%DAY_NAME%` instead of "Monday")

**Solutions:**

* Check spelling and case sensitivity
* Ensure you're using double curly braces: `{{ variable.path }}`
* Verify the variable name matches exactly

### Customer Variables Empty

**Issue**: `{{ customer.* }}` variables are empty or removed

**Solutions:**

* Ensure visitor has a customer session (email or `is_customer` flag)
* Check that customer has made at least one purchase
* Verify the variable name is correct

### Query Parameters Not Working

**Issue**: `{{ query.* }}` variables are empty

**Solutions:**

* Verify the parameter exists in the URL
* Check parameter name spelling (case-sensitive)
* Ensure the URL includes `?parameter=value` format

## Related Documentation

* [Order Tag](/pages/order-tag) - Display customer order history
* [Product Item Tag](/pages/product-item-tag) - Display product listings
* [Collection Item Tag](/pages/collection-item-tag) - Display collection entries


# Page Variants
Source: https://docs.elasticfunnels.io/pages/page-variants

Create and manage multiple versions of your pages for split testing and optimization

Page variants let you run multiple versions of the same page for split tests, fresh angles, or different campaigns.

## Creating Page Variants

### Add a New Variant

1. Go to **Pages** → Select your page
2. Click **"Add Variant"** or **"Create Variant"**
3. The system automatically creates a new variant with the next number (V1, V2, V3, etc.)
4. Edit the new variant with your desired changes

### Variant Naming System

ElasticFunnels uses a **numerical system** instead of letters:

* **V1** - First variant (original)
* **V2** - Second variant
* **V3** - Third variant
* And so on...

**Why numbers instead of letters?**

* **Clearer progression** - Easy to understand the sequence
* **No confusion** - No ambiguity about which comes first
* **Unlimited variants** - Can create as many as needed (V1, V2, V3...V100)

## Managing Variants

### Set Active Variant

1. **Select the variant** you want to make active
2. **Click "Set as Active"** or toggle the active status
3. **The active version changes** for the page
4. **Variant slugs** can be used when you need a separate URL for a specific variant

### Variant URLs

* The primary variant uses the page's normal URL, for example `https://yoursite.com/page`.
* Additional variants are separate page records and can have their own `variant_slug`.
* If a variant slug is configured, it can be served as its own URL, for example `https://yoursite.com/page-v2`.
* Funnel and Page Events variant nodes can also route traffic to a variant directly.

### Variant Status

Each variant has a status:

* **Active** - Currently serving to visitors
* **Draft** - Work in progress, not live
* **Paused** - Temporarily disabled
* **Archived** - Saved for reference but not active

## Serving a variant from Page Events

The **Load Another Page** node (`page_variant`) renders another page's content **at the current URL** — no redirect, no URL change. It is how a variant gets served without giving it its own address.

| Field | Description |
| - | - |
| **Page** | The variant to load. Stored as `value`; the slug is filled in automatically. |
| **Load & Override Page Events** | Off by default — the variant inherits the primary page's event graph. Turn it on to give the variant its own events. |

<Warning>
  **Load & Override Page Events re-runs the whole event pass** for the newly loaded page. That is capped at three reloads per request, so avoid chains where each variant loads another variant that also overrides its events.
</Warning>

The node is skipped in preview mode, so previewing a page always shows the page itself.

## Split Testing with Variants

### Page-level split testing

To split traffic between variants at one URL:

1. **Create the variants** with different content.
2. In **Page Events**, add a **Split Test** node and set **Total Variants**.
3. A **Traffic Distribution** node is created per output — set the percentages.
4. Under each Traffic Distribution node, attach a **Load Another Page** pointing at that variant.
5. Save. The split-test record is created and the node gains a **View Results** link.

```mermaid theme={null}
flowchart LR
  E[Loaded] --> ST[Split Test<br/>value: 2]
  ST -->|Output 1| W1[Traffic Distribution 50%]
  ST -->|Output 2| W2[Traffic Distribution 50%]
  W1 --> P1[Load Another Page<br/>V1]
  W2 --> P2[Load Another Page<br/>V2]
```

<Note>
  Testing **one section** of a page rather than the whole page? Use a component split test instead — it is cheaper to build and easier to read. See [Split Testing](/funnels/split-testing#which-kind-of-test-do-i-want).
</Note>

### Funnel-level integration

Variants work with funnel split testing:

* **Split test node** can direct traffic to different variants
* **Purchase tracking** attributes conversions to specific variants
* **Analytics** show performance data for each variant

## Best Practices

### Variant Organization

* **Clear naming** - Use descriptive names beyond just V1, V2, V3
* **Version notes** - Document what changed in each variant
* **Purpose tracking** - Record why each variant was created
* **Performance baseline** - Always keep your original as a control

### Testing Strategy

* **Test one element** at a time for clear results
* **Significant changes** - Make meaningful differences between variants
* **Statistical significance** - Run tests long enough for reliable data
* **Document results** - Keep notes on what worked and what didn't

### Content Management

* **Consistent structure** - Keep similar layouts when possible
* **Asset management** - Organize images and videos for each variant
* **Mobile optimization** - Ensure all variants work on mobile devices
* **Loading speed** - Optimize each variant for fast loading

## Advanced Variant Usage

### Campaign-Specific Variants

Create variants for different marketing campaigns:

* **Traffic source optimization** - Different versions for different sources
* **Seasonal campaigns** - Holiday or event-specific versions
* **Geographic targeting** - Location-specific content
* **Device optimization** - Mobile vs desktop optimized versions

### Personalization

Use variants for personalized experiences:

* **Affiliate-specific** - Different versions for different affiliates
* **User segment** - Different content for different user types
* **Purchase history** - Different offers based on past purchases
* **Behavior-based** - Different content based on user actions

## URLs and Routing

### Reaching a specific variant

There are two ways, and **no `v=` query parameter**:

* **By its own slug** — the active variant answers on the page's `slug`; every other variant answers on its `variant_slug` (for example `page-v2`). A variant without a `variant_slug` has no URL of its own.
* **By a Load Another Page node** — the variant renders at the primary page's URL, with nothing in the address bar to reveal it. This is what you want for split tests.

**SEO considerations** — use canonical tags when several slugs serve near-identical content.

### Page Events Integration

Variants work with Page Events:

* **Load Another Page** - Serve a variant at the primary URL
* **Query parameter conditions** - Route to a variant based on the incoming URL
* **Dynamic content** - Swap sections rather than the whole page
* **Conditional logic** - Different actions for different variants

### Funnel Integration

Variants integrate with funnel flows:

* **Split test routing** - Direct traffic to specific variants
* **Purchase attribution** - Track which variant drove the conversion
* **Upsell sequences** - Different upsells based on variant performance

## Analytics and Reporting

### Performance Metrics

Track key metrics for each variant:

* **Conversion rate** - Percentage of visitors who convert
* **Revenue per visitor** - Average revenue generated
* **Bounce rate** - Percentage who leave immediately
* **Time on page** - How long visitors stay
* **Click-through rate** - Engagement with call-to-action buttons

### Comparison Tools

* **Side-by-side comparison** - Compare variant performance
* **Statistical significance** - Determine if differences are meaningful
* **Confidence intervals** - Understand the reliability of results
* **Performance trends** - Track improvement over time

## Troubleshooting

### Common Issues

* **Variants not loading** - Check the variant's `variant_slug`, or that a **Load Another Page** node is on the branch being taken. A condition on its own only picks a path — it does not load a page.
* **Preview always shows the primary page** - Expected: **Load Another Page** is skipped in preview mode.
* **Split tests not working** - Verify funnel or page event configuration
* **Analytics not tracking** - Ensure proper tracking setup for variants
* **Content not updating** - Clear cache and check variant status

### Testing Your Variants

1. **Direct URL access** - Test each variant URL directly
2. **Split test functionality** - Verify random distribution works
3. **Mobile testing** - Check all variants on mobile devices
4. **Cross-browser testing** - Ensure compatibility across browsers
5. **Performance testing** - Check loading speed for each variant

<Note>
  Use variants for meaningful tests only. Too many small variants make results harder to read.
</Note>


# Privacy & consent
Source: https://docs.elasticfunnels.io/pages/privacy-consent

Ask visitors for cookie and marketing consent on your funnel pages, hold ad pixels until they say yes, and read the choice from your own scripts.

ElasticFunnels can show a cookie consent banner on your funnel pages, hold
advertising pixels until the visitor agrees, and record what each visitor chose.
You decide where it applies, how it looks and what it says.

<Warning>
  **Consent is off by default.** Until you turn it on under **Settings → Privacy &
  consent**, nothing changes on your pages: no banner, and every pixel runs as
  before. If your brand gets visitors from the EU, the EEA or the UK, the settings
  tab shows what share of your visitors came from there in the last 30 days.
</Warning>

<Note>
  This page explains what the product does. It is not legal advice. The built-in
  banner texts and the default regions are a starting point: check them, and your
  cookie and privacy policies, with your own counsel.
</Note>

***

## Turning it on

<Steps>
  <Step title="Pick how consent is collected">
    Go to **Settings → Privacy & consent**. Under **Consent banner**, set **How
    consent is collected**:

    | Option | What happens |
    | - | - |
    | **ElasticFunnels banner** | We show a banner to visitors in the regions you choose. Ad pixels wait until they accept. |
    | **My own consent tool** | You run your own consent tool (Cookiebot, OneTrust, Usercentrics and so on). We show no banner and read the choice it reports. See [Using your own consent tool](#using-your-own-consent-tool). |
    | **Not required** | The default. No banner anywhere and nothing is held back. |
  </Step>

  <Step title="Choose where to ask">
    Under **Where to ask**, switch regions on or off. Visitors are placed by the
    country of their IP address.

    | Region | Default |
    | - | - |
    | **European Union and EEA** (the 27 EU countries plus Iceland, Liechtenstein and Norway) | On |
    | **United Kingdom** (with the Channel Islands, the Isle of Man and Gibraltar) | On |
    | **Switzerland** | Off |
    | **Everywhere else** | Off |
    | **Visitors whose country cannot be detected** | On |

    Outside the regions you switch on, pages behave as if consent were off.
  </Step>

  <Step title="Add your policy links and save">
    Under **Policy links**, add your **Cookie policy URL** and **Privacy policy
    URL** (a full `https://` address, or a path on your own domain such as
    `/privacy`). They appear in the banner. Press **Save**.
  </Step>
</Steps>

***

## What is held until the visitor agrees

In a region where you ask for consent:

* **Ad pixels from your tracking integrations** (Meta, Google Ads, TikTok,
  LinkedIn, Bing, Snapchat, Pinterest, Reddit, X, Outbrain) are sent to the page
  switched off and start only after the visitor accepts **marketing**.
* **Google Analytics** from your integrations waits for an **analytics** yes.
* **Your custom tracking scripts** (Pages → Tracking scripts) run as usual,
  because they are often needed for the page to work (affiliate link rewriting,
  for example). Switch on **Also hold my custom tracking scripts** under **Before
  the visitor chooses** to hold them for marketing consent too.
* **Persistent identifiers.** Until the visitor accepts analytics, ElasticFunnels
  sets no long-lived visitor cookie and uses no device id: your funnel reports
  still count the visit, tied to that one visit only.

**ElasticFunnels analytics** (under **Before the visitor chooses**) decides what
happens to our own first-party page analytics before a choice:

| Option | What happens |
| - | - |
| **Keep running, without persistent IDs until consent** | The default. Page views and events are recorded for the visit, with no long-lived id. |
| **Wait for analytics consent** | Nothing from the visitor's browser is recorded until they accept analytics. |

A visitor who declines analytics is never tracked by the browser, whichever
option you pick. Orders are always recorded.

### Holding a script of your own by hand

You can hold any script or pixel in your page HTML the same way. Write it with
`type="text/plain"`, a `data-ef-consent` category and `data-ef-src` instead of
`src`:

```html theme={null}
<!-- Runs only after the visitor accepts marketing -->
<script type="text/plain" data-ef-consent="marketing"
        data-ef-src="https://example.com/pixel.js"></script>

<!-- Inline code works too -->
<script type="text/plain" data-ef-consent="analytics">
  console.log('analytics allowed');
</script>

<!-- Images and iframes: data-ef-src instead of src -->
<img data-ef-consent="marketing" data-ef-src="https://example.com/p.gif" alt="">
```

The category is `marketing` or `analytics`. When the visitor agrees, the element
is switched on in page order.

<Warning>
  Held elements are switched on by the consent script, which is only on the page
  when consent is on for the brand. If you set the brand back to **Not required**,
  remove `type="text/plain"` and use `src` again, or these elements never run.
</Warning>

***

## How the banner looks

Under **Display style**:

| Style | What it looks like |
| - | - |
| **Floating card** | A rounded card at the bottom of the page. The default. |
| **Bottom bar** | A full-width strip along the bottom. |
| **Blocking (card over a dimmed page)** | The card over a dimmed page until the visitor chooses. |

A blocking banner gets more choices made; the card and the bar interrupt less. In
every style, **Reject all** sits next to **Accept all** at the same size, and
**Choose** opens the category switches (necessary, analytics, marketing). The
blocking style keeps keyboard focus inside the card and ignores Escape until a
choice is made, and declining still lets the visitor into the page.

**Button colour** sets the colour of **Accept all**. Leave it empty to use your
brand colour, or near-black when there is none. The banner uses your page's font.

***

## Texts and languages

The banner has built-in texts in 38 languages: every official language of the
EU and EEA, plus Turkish, Russian, Ukrainian, Arabic, Hebrew, Japanese, Korean,
Chinese, Hindi, Indonesian, Thai and Vietnamese. It picks one per visitor:

1. the language of the page (its `<html lang>`, or the language it is served in
   when you use translations);
2. otherwise, the visitor's browser language;
3. otherwise, English.

Arabic and Hebrew are shown right to left.

Under **Banner text**, pick a **Language** and write your own text for any field.
Each empty field shows the built-in text in grey and uses it; **Reset to
default** clears your text. A field you leave empty in one language falls back
to that language's built-in text, then to your English text, then to ours.

**Translate with AI** fills the selected language from your English texts (or
from your own texts when the target is English). It shows how many AI credits it
will use before it runs, and nothing is saved until you press **Save**.

<Note>
  The built-in texts were machine-written and have not all been reviewed by native
  speakers yet. Read them in the languages your visitors use.
</Note>

**Ask everyone again** (switch on **Ask all visitors again after saving**) makes
every stored choice obsolete, so the banner shows again. Use it after you change
what you track or who you share it with.

***

## Checkout email opt-in

Separate from cookie consent, **Checkout email opt-in** records whether a buyer
agreed to receive marketing email from you. Switch on **Show an email opt-in box
on checkout pages** to add an unticked box above the order button. Its text is
under **Banner text** as **Checkout email opt-in box text**, per language. A
checkout page that already has its own `allow_emails` box keeps it.

***

## SMS and email opt-in boxes on checkout and upsell pages

You can add your own opt-in boxes to a **checkout page** or an **upsell page**. In the page builder,
drag the **Customer Flag** block (Checkout category) onto the page and pick **SMS marketing** or
**Email marketing** in its settings; in the
code editor, write the checkbox yourself:

```html theme={null}
<label>
  <input type="checkbox" name="allow_sms" value="1">
  Yes, text me offers and order updates. Msg & data rates may apply. Reply STOP to opt out.
</label>
```

| Box | Records |
| - | - |
| `name="allow_sms"` | The buyer agreed to SMS marketing |
| `name="allow_emails"` | The buyer agreed to email marketing |

A ticked box is stored on that order as a flag (`allow_sms` or `allow_emails`). An unticked box stores
nothing. On an **upsell page**, the box is read when the buyer clicks the accept link (`[UPSELL=...]`),
for one-click and redirect upsells alike, and stored on the upsell order. A buyer who declines the
upsell is not recorded either way.

<Note>
  The flag records **that** the buyer ticked the box, not the words next to it. If you send SMS in the
  US, keep a copy of the exact opt-in text each page used, with the date it went live, for your consent
  records.
</Note>

***

## For developers: the `window.ef.consent` API

On pages where consent is on for the brand, `window.ef.consent` is available
from the `<head>` onwards.

| Method | What it does |
| - | - |
| `get()` | Returns `{ analytics, marketing, required, region, has_choice }`. |
| `set({ analytics, marketing })` | Stores a choice, as if the visitor made it, and switches on what it allows. |
| `allowed(category)` | `true` when `'analytics'`, `'marketing'` or `'necessary'` may run now. |
| `open()` | Opens the banner with the category switches (ElasticFunnels banner only). |
| `onChange(fn)` | Calls `fn(state)` with the same object as `get()` whenever the choice changes. |

`required` is `true` when the visitor is in a region where you ask. `region` is
one of `eea`, `uk`, `ch`, `rest`, `unknown`.

```js theme={null}
const consent = window.ef.consent;

if (consent.allowed('marketing')) {
  // load something that needs marketing consent
}

consent.onChange((state) => {
  if (state.marketing) {
    // the visitor just said yes to marketing
  }
});
```

<Note>
  `window.efConsent` is the same object, kept for integrations written against it.
  Use `window.ef.consent` in new code.
</Note>

### Events

On every change, and once when the page loads with a choice the visitor made
earlier, the page fires these events on `window`:

| Event | When |
| - | - |
| `ef-consent` | Every time. |
| `ef-consent-accepted` | Analytics and marketing are both allowed. |
| `ef-consent-rejected` | Analytics and marketing are both refused. |

Each carries the same `detail`:

```js theme={null}
{
  analytics: true,     // analytics allowed
  marketing: false,    // marketing allowed
  required: true,      // the visitor is in a region where you ask
  region: 'eea',       // eea | uk | ch | rest | unknown
  source: 'banner'     // banner | api | cmp | stored
}
```

`source` is `banner` for a click in our banner, `api` for `window.ef.consent.set`,
`cmp` for a choice read from your own consent tool, and `stored` for the choice
announced on page load.

```js theme={null}
window.addEventListener('ef-consent', (event) => {
  console.log('consent now', event.detail);
});

window.addEventListener('ef-consent-accepted', () => {
  // everything is allowed
});
```

### Google Tag Manager

Every change (and the stored choice on page load) is also pushed to `dataLayer`:

```js theme={null}
{ event: 'ef_consent_update', ef_consent: { analytics: true, marketing: true } }
```

In Google Tag Manager, create a **Custom Event** trigger with the event name
`ef_consent_update`, and two **Data Layer Variables** named
`ef_consent.analytics` and `ef_consent.marketing`. Then fire a tag only when, for
example, `ef_consent.marketing` equals `true`.

With **Send Google Consent Mode signals** on (the default), the page also sets
Google Consent Mode defaults (`denied` until the visitor chooses, in regions
where you ask) and sends an update after each choice, so Google tags you add
yourself follow it.

### A "Cookie settings" link

Give visitors a way to change their mind. Any element with
`data-ef-consent-open` reopens the banner (for visitors in a region where you
ask, or who made a choice before):

```html theme={null}
<a href="#" data-ef-consent-open>Cookie settings</a>
```

### Using your own consent tool

Set **How consent is collected** to **My own consent tool**. We show no banner,
and pixels wait as described above until your tool reports a choice. Report it
with:

```js theme={null}
window.ef.consent.set({ analytics: true, marketing: false });
```

Call it whenever the visitor makes or changes a choice. Two signals are picked
up without any code:

* **Google Consent Mode**: a `gtag('consent', 'update', ...)` from your tool.
  `analytics_storage` sets analytics; `ad_storage` (with `ad_user_data` not
  denied) sets marketing.
* **IAB TCF v2**: when your tool exposes `__tcfapi`, marketing needs purposes
  1, 3 and 4, and analytics needs purposes 1 and 8.


# Product Item Tag
Source: https://docs.elasticfunnels.io/pages/product-item-tag

Display dynamic product listings filtered by type, classification, or specific product codes

The `<product-item>` tag allows you to create dynamic product listings on your pages. It automatically loops through products that match your criteria and displays them using a template you define.

## Overview

The product item tag is perfect for:

* Product catalogs and listings
* Featured products sections
* Related products
* Category pages
* Upsell product displays

Each product matching your filter criteria will be rendered using your template, with product data automatically inserted.

## Basic Usage

### Simple Product Listing

```html theme={null}
<product-item data-type="any">
  <div class="product">
    <h3>{product.name}</h3>
    <p>{product.price}</p>
  </div>
</product-item>
```

### With Filtering

```html theme={null}
<product-item data-type="physical" data-classification="main">
  <div class="product-card">
    <img src="{product.image_url}" alt="{product.name}">
    <h4>{product.name}</h4>
    <p class="price">{product.price}</p>
    <p>{product.description}</p>
  </div>
</product-item>
```

## Attributes

### Required Attributes

#### `data-type`

Filters products by type.

**Values:**

* `"any"` - All product types (default if not specified)
* `"physical"` - Physical products only
* `"digital"` - Digital products only
* `"service"` - Service products only
* Any other product type defined in your system

**Example:**

```html theme={null}
<product-item data-type="physical">
  <!-- Only physical products will be displayed -->
</product-item>
```

### Optional Attributes

#### `data-classification`

Filters products by classification.

**Values:**

* `"any"` - All classifications (default)
* `"main"` - Main products only
* `"upsell"` - Upsell products only
* `"downsell"` - Downsell products only
* `"bump"` - Bump products only
* Any other classification defined in your system

**Example:**

```html theme={null}
<product-item data-type="any" data-classification="upsell">
  <!-- Only upsell products will be displayed -->
</product-item>
```

#### `data-codes`

Filter by specific product codes (comma-separated).

**Format**: Comma-separated list of product codes

**Example:**

```html theme={null}
<product-item data-codes="PROD001,PROD002,PROD003">
  <!-- Only products with these codes will be displayed -->
</product-item>
```

#### `id`

Optional element ID applied to each product wrapper.

**Example:**

```html theme={null}
<product-item data-type="physical" id="product-item">
  <!-- Each product will be wrapped in <div id="product-item"> -->
</product-item>
```

## Product Placeholders

Within the `<product-item>` template, you can use these placeholders to display product information:

### Standard Product Fields

Use `{product.field_name}` to access standard product attributes:

* `{product.name}` - Product name
* `{product.code}` - Product code
* `{product.price}` - Product price
* `{product.description}` - Product description
* `{product.image_url}` - Product image URL
* `{product.type}` - Product type
* `{product.classification}` - Product classification
* `{product.currency}` - Currency code
* `{product.status}` - Product status
* `{product.primary_download_url}` - Primary downloadable file URL

**Example:**

```html theme={null}
<product-item data-type="physical">
  <div class="product">
    <img src="{product.image_url}" alt="{product.name}">
    <h3>{product.name}</h3>
    <p class="code">SKU: {product.code}</p>
    <p class="price">${product.price}</p>
    <p>{product.description}</p>
  </div>
</product-item>
```

### Custom Product Attributes

Use `{product.attributes.attribute_name}` to access custom product attributes.

**Example:**

```html theme={null}
<product-item data-type="physical">
  <div class="product">
    <h3>{product.name}</h3>
    <p>Color: {product.attributes.color}</p>
    <p>Size: {product.attributes.size}</p>
    <p>Material: {product.attributes.material}</p>
  </div>
</product-item>
```

**Note**: Custom attributes must be defined in your product settings. If an attribute doesn't exist, it will be empty.

### Downloadable Files

Digital and bonus downloads are exposed through `{product.product_files}`. Each file can include `purpose`, `title`, `description`, `image`, `file`, `is_primary`, `sort_order`, and `metadata`.

Use these helper shapes when you want filtered access:

* `{product.digital_files}` - Downloadable files with `purpose: "digital"`
* `{product.bonus_files}` - Downloadable files with `purpose: "bonus"`
* `{product.primary_download_url}` - First primary file URL across available product files

## Filtering Examples

### Filter by Type Only

```html theme={null}
<!-- Show only digital products -->
<product-item data-type="digital">
  <div class="digital-product">
    <h3>{product.name}</h3>
    <p>Download: {product.attributes.download_link}</p>
  </div>
</product-item>
```

### Filter by Classification

```html theme={null}
<!-- Show only main products -->
<product-item data-type="any" data-classification="main">
  <div class="main-product">
    <h3>{product.name}</h3>
    <p>{product.price}</p>
  </div>
</product-item>
```

### Filter by Specific Codes

```html theme={null}
<!-- Show only specific products -->
<product-item data-codes="FEATURED001,FEATURED002,FEATURED003">
  <div class="featured-product">
    <span class="badge">Featured</span>
    <h3>{product.name}</h3>
    <p>{product.price}</p>
  </div>
</product-item>
```

### Combined Filters

```html theme={null}
<!-- Physical upsell products -->
<product-item data-type="physical" data-classification="upsell">
  <div class="upsell-product">
    <h3>{product.name}</h3>
    <p>Add to order: {product.price}</p>
  </div>
</product-item>
```

## Complete Example

Here's a complete example of a product catalog page:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Our Products</title>
  <style>
    .product-grid {
      display: grid;
      grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
      gap: 20px;
      padding: 20px;
    }
    .product-card {
      border: 1px solid #ddd;
      border-radius: 8px;
      padding: 15px;
      text-align: center;
    }
    .product-card img {
      width: 100%;
      height: 200px;
      object-fit: cover;
      border-radius: 4px;
    }
    .product-card h3 {
      margin: 10px 0;
    }
    .product-card .price {
      font-size: 1.5em;
      font-weight: bold;
      color: #1d4ed8;
    }
  </style>
</head>
<body>
  <h1>Our Products</h1>
  
  <div class="product-grid">
    <product-item data-type="physical" data-classification="main">
      <div class="product-card">
        <img src="{product.image_url}" alt="{product.name}">
        <h3>{product.name}</h3>
        <p class="price">${product.price}</p>
        <p>{product.description}</p>
        <button>Add to Cart</button>
      </div>
    </product-item>
  </div>
</body>
</html>
```

## How It Works

1. **Tag Detection**: The system finds all `<product-item>` tags in your page
2. **Filter Application**: Products are filtered based on `data-type`, `data-classification`, and `data-codes` attributes
3. **Template Rendering**: For each matching product, the template is rendered
4. **Placeholder Replacement**: Product placeholders (`{product.*}`) are replaced with actual product data
5. **Output**: Each product is wrapped in a `<div>` with the specified `id` (if provided)

## Best Practices

### Performance

* **Limit Results**: Use specific `data-codes` when you only need a few products
* **Filter Early**: Use `data-type` and `data-classification` to reduce the product pool
* **Optimize Images**: Ensure product images are optimized for web

### User Experience

* **Consistent Layout**: Keep product card layouts consistent
* **Clear Pricing**: Always display price clearly
* **Product Images**: Include product images for better visual appeal
* **Call-to-Action**: Include clear CTAs (buy buttons, learn more, etc.)

### Template Design

* **Responsive**: Design templates that work on mobile and desktop
* **Accessible**: Use semantic HTML and proper alt text for images
* **Flexible**: Design templates that work with varying product data

## Troubleshooting

### No Products Displaying

**Possible Causes:**

* No products match your filter criteria
* `data-type` is too restrictive
* Product codes in `data-codes` don't exist
* Products are inactive or unpublished

**Solutions:**

* Check your filter attributes
* Verify products exist in your system
* Try `data-type="any"` to see all products
* Check product status in your dashboard

### Placeholders Not Replacing

**Issue**: Placeholders show as literal text (e.g., `{product.name}`)

**Solutions:**

* Check placeholder spelling (case-sensitive)
* Ensure you're using `{product.*}` format, not `%product.*%`
* Verify the product field exists

### Custom Attributes Empty

**Issue**: `{product.attributes.*}` is empty

**Solutions:**

* Verify the custom attribute is defined in product settings
* Check attribute name spelling (case-sensitive)
* Ensure the attribute has a value for that product

## Related Documentation

* [Collection Item Tag](/pages/collection-item-tag) - Display collection entries
* [Page Variables](/pages/page-variables) - Use variables and placeholders
* [Buy Links](/products/buy-links) - Add purchase links to products


# Rendering pipeline
Source: https://docs.elasticfunnels.io/pages/rendering-pipeline

The four layers that transform a page — page-event containers, the backend template engine, the browser reactive engine — and the order they run in.

A published ElasticFunnels page is **one HTML string that is rewritten several times**, first on the server and then in the browser. Four different systems touch it, each with its own syntax and its own moment in the sequence. They look similar in the source, which is why they get mixed up.

<Warning>
  These are **not** one system with alternative spellings. A construct from one layer placed inside a construct from another layer does not compose the way it looks like it does — the outer one has usually already finished running before the inner one starts. The [Wrong vs right](#wrong-vs-right) section shows the failures this produces.
</Warning>

## The four layers

| Layer | Looks like | Runs | Owns |
| - | - | - | - |
| **Containers** (page events) | `<split-test id="…">`, `<dynamic-container id="…">`, `<inline-split-test>` | Server, **first**, before any template engine | Choosing *which* markup goes in a slot |
| **Page pipeline** (tags & components) | `<component type="…">`, `[BUY=…]`, `<product-item>`, `{customer.first_name}` | Server, second | Expanding platform tags into HTML |
| **Backend template engine** | `{{ … }}`, `@if`, `@foreach`, `@set`, `@component`, `@extends`/`@block` | Server, **last** thing before the response is sent | Everything decided at request time |
| **Frontend reactive engine** | `[[ … ]]`, `<template-if>`, `<template-foreach>`, `<template-set>`, `ef-*` / `data-ef-*` bindings, `window.efScope` | Browser, after `DOMContentLoaded` | Everything that changes without a reload |

Two consequences follow from the order alone, and they are the source of most confusion:

* **The backend engine never sees `[[ ]]`.** It only recognises `{{ }}` and `@` directives; `[[ ]]` is inert text to it and is passed through to the browser untouched.
* **The frontend engine never sees `{{ }}` or `@if`.** By the time the browser has the HTML, those are already rendered away. Anything left over is literal text and the frontend engine ignores it.

## Order of execution

<Steps>
  <Step title="Server — resolve the page">
    Domain → funnel → page. The page HTML is loaded from the database exactly as you saved it.
  </Step>

  <Step title="Server — run the page-events graph (backend nodes)">
    The per-page node graph executes. Nodes that rewrite HTML do it **here**, on the raw saved source:

    * `component_split_test` fills a `<split-test>` container with the selected variant component
    * `dynamic_container` fills a `<dynamic-container>` with a chosen component
    * `page_variant` can swap the whole page out
    * `script_rule`, `url_redirect`, `add_tag`, `set_merchant`, … run their side effects

    Nodes marked as frontend are collected and shipped to the browser as JSON to run later.

    <Note>
      This step happens **before** the backend template engine and **long before** the browser. That is the single most important fact on this page.
    </Note>
  </Step>

  <Step title="Server — expand platform tags and components">
    `<component type="code">` and the builder's component placeholders are resolved (each component recursively runs this entire pipeline, including its own template render). Then inline split tests, purchase tags (`[BUY=]`, `[UPSELL=]`, `[QUICKBUY=]`, add-to-cart, subscription upsell), video tags, `<product-item>` / `<collection-item>`, order and date tags, `{customer.*}`, merchant tags, brand variables, quizzes, courses, and the checkout or cart processor (which is what seeds `window.efScope.checkout`).
  </Step>

  <Step title="Server — render the backend template engine">
    Now, and only now, `{{ }}` and the `@` directives run: `@extends`/`@block`/`@yield` assemble the layout, `@if`/`@elseif`/`@else`, `@foreach`, `@set`, `@component`, variables and filters. Asset URLs are rewritten just before this.

    Because `@extends` can pull in markup that was not in the page source, purchase tags are swept a second time after the render.
  </Step>

  <Step title="Server — prepare for the browser">
    Elements containing unresolved `[[ … ]]` get `data-ef-cloak` so they are hidden until the frontend engine runs; `src`/`srcset`/`poster` attributes containing `[[ ]]` are deferred so the browser does not fetch a nonsense URL. The result is wrapped in the site layout, which injects the cloak stylesheet, the frontend page-events JSON, and the JS bundle. **The response is sent.**
  </Step>

  <Step title="Browser — before JS runs">
    Every tag the frontend engine consumes — `template-if`, `template-else-if`, `template-if-else`, `template-else`, `template-foreach`, `template-vars`, `template-set`, `template-partial` / `partial` — is `display: none` from the cloak stylesheet, as is anything carrying `data-ef-cloak`. Nothing an engine tag wraps is painted before the engine has decided what to keep. Containers are *not* hidden — they were already resolved on the server, so their content is final HTML.
  </Step>

  <Step title="Browser — mount the frontend engine">
    On `DOMContentLoaded` (deferred one frame on checkout pages so the cart plugin can populate scope first), `initTemplateScope()` runs: it makes `window.efScope` reactive, copies the URL query string into `efScope.query`, then applies directives in a fixed order — `template-vars` → `template-set` → `template-partial` → `template-foreach` → `template-if` → `[[ ]]` interpolation — and finally wires the `ef-*` bindings and event handlers.
  </Step>

  <Step title="Browser — stay reactive">
    Any mutation of `window.efScope` (or an explicit `notifyScopeUpdated()` / `ef-scope-updated` event) re-evaluates conditions, re-renders loops, and refreshes bindings. Frontend page-event nodes and `window.ef` scripts run in this phase too.
  </Step>
</Steps>

## Which syntax do I use for…

| I want to… | Use | Not |
| - | - | - |
| Print a value known at request time (brand variable, query param, product, order, customer, device) | `{{ var.offer_name }}` | `[[ var.offer_name ]]` — `var` is backend-only, by design |
| Print a value that changes in the browser (cart, quantity, coupon, wizard step) | `[[ cartCount ]]` | `{{ }}` — it is long gone before the value exists |
| Show/hide something decided at request time | `@if(…) … @endif` | `<template-if>` for something that can never change |
| Show/hide something that flips without a reload | `<template-if data-condition="…">` | `@if` — the server already committed |
| Loop over server data | `@foreach(item in items) … @endforeach` | — |
| Loop over reactive data | `<template-foreach data-each="item in items">` | — |
| Hold a temporary value server-side | `@set(name = value)` | — |
| Hold a temporary value browser-side | `<template-set data-variable="n" data-value="expr">` | — |
| Reuse a saved component | `@component("code", { key: value })` | `<template-component …>` — **not implemented**, see below |
| Swap a section per visitor, with no test | `<dynamic-container id="…" name="…">` + a `dynamic_container` node | Writing the alternatives inline |
| A/B test one section of a page | `<split-test id="…" name="…">` + a `component_split_test` chain | Writing the variants inline |
| A/B test alternatives written inline in the page, with no graph | `<inline-split-test id="…">` with `<variant name="…" weight="…">` children | `<split-test>` |
| A/B test a whole page | Page variants | A container |

## `var.*` is a backend facility

Brand variables (`variables.json`, the Variables screen, funnel overrides) belong to the **backend template engine** — the third layer, on the server. They are resolved with `{{ var.x }}` while the server renders, and they are deliberately **not** copied into `window.efScope` — the browser never receives the variable set, only the values the page chose to print. That is by design, not a missing feature: it keeps a brand's full variable list (prices, internal codes, per-funnel overrides) off the wire, and it keeps `{{ }}` and `[[ ]]` on opposite sides of the response.

So `[[ var.x ]]` resolves to nothing — there is no `var` in browser scope to resolve it against.

When you *do* want a brand variable client-side, hand it over explicitly. The backend prints the value, the browser stores it under a name of your choosing:

```html theme={null}
<script>
  window.efScope = window.efScope || {};
  window.efScope.offerName = {{ var.offer_name | json | raw }};
</script>

<p>[[ offerName ]]</p>
```

`| json` quotes and escapes the value so strings, numbers and objects all land as valid JavaScript. Assign it before the engine mounts (an inline `<script>` in the page body is fine) and `[[ offerName ]]` renders on first paint; assign it later and the scope's reactivity re-renders the bindings for you.

## `<template-component>` does not exist

This one has to be stated plainly, because it appears in several older reference tables and the linter tag-balances it as though it were real:

<Warning>
  **No engine implements `<template-component data-component-name="…">`.** The backend template engine only matches the literal `@component` directive. The page pipeline only matches `<component type="code">` and the builder's `data-component-type` placeholders. The frontend engine has no component directive at all — its complete tag list is `template-if`, `template-else-if`, `template-if-else`, `template-else`, `template-foreach`, `template-vars`, `template-set`, `template-partial` / `partial`.

  A `<template-component>` element therefore reaches the browser as an unknown HTML element. It is not even hidden by the cloak stylesheet. Because it is normally written self-closing or empty, it renders **nothing at all, with no error** — the most expensive kind of failure.
</Warning>

The ways to include a component that *do* work:

| Form | Resolved by | When |
| - | - | - |
| `@component("code", { key: value })` | Backend template engine | Step 4 — during the template render |
| `<component type="code">` | Page pipeline | Step 3 — before the template render. This is what a `dynamic_container` node emits |
| Component split test / dynamic container node | Page-events graph | Step 2 — the component's HTML is spliced in as the container's content |

In every case the component's own HTML is then run through the full pipeline itself, so the component can use `{{ }}`, `@if`, `[[ ]]` and the rest normally.

## Containers are not a template engine

`<split-test>` and `<dynamic-container>` are **slots**. They contain no logic. They do not evaluate anything. They mark a position in the page and say "the page-events graph may replace this".

### The content model

A container's inner content is the **default**. At request time exactly one of two things renders:

1. **A test or a rule is bound to this container** — the graph picks a component and that component's HTML replaces the container, wrapper tag and all. For a split test the wrapper becomes a `div` carrying `data-sid` / `data-fnid` / `data-cid` for analytics; for a dynamic container it becomes a `div` keeping the original `id`.
2. **Nothing is bound** — no split test running, no graph, no matching rule — and the **default content renders as-is, with the wrapper tag gone**.

That is the whole model. The default is what you want a visitor to see when no test is running; the alternatives live in the graph, never in the markup.

<Note>
  **Known bug, fix in flight.** In the current renderer an unbound container can survive into the response as a literal `<split-test id="…">…</split-test>` element instead of being unwrapped. A real published page has been observed doing this. The default content is still visible (unknown elements render their children) but the wrapper survives, which shows up in view-source and can break block layout because unknown elements are inline-level. Some unbound paths already unwrap correctly; the remaining ones are being fixed to match the model above. Write your pages against the model, not against the current output.
</Note>

### Why variants belong in the graph, not in the markup

Because only one of the two outcomes above can ever render, **markup that lists several alternatives inside one container is always wrong**. Two sibling components inside one container is not "two variants" — it is one default that happens to contain both, and if a test is running neither of them renders. There is no syntax for "pick one of these inline children"; that job belongs to the graph, which is also where the weights, the assignment cookie, the winner selection and the reporting live.

A single component inside a container is fine — it is just the default content.

If you genuinely want the alternatives written inline in the page, that is a different tag: `<inline-split-test>` with `<variant name="…" weight="…">` children, which does select among its own children at request time and needs no graph.

### A container inside a condition

This is the interaction that surprises people, and it fails the same way for both engines:

```html theme={null}
{{-- Backend condition --}}
@if(query.step eq 1)
  <split-test id="hero" name="Hero">…default…</split-test>
@endif
```

```html theme={null}
<!-- Frontend condition -->
<template-if data-condition="quizStep === 0">
  <split-test id="hero" name="Hero">…default…</split-test>
</template-if>
```

**Neither condition gates the container.** Containers are resolved in step 2. `@if` runs in step 4 and `<template-if>` runs in step 7 — both strictly later. So on every single request:

* the graph runs, selects a variant, and writes the assignment cookie
* the visitor is enrolled in the test and the test id is added to the session's split-test attribution list
* *then* the condition removes the resolved markup from the page

The visitor is counted as having seen a variant they never saw. Split-test results drift, and conversions get attributed to a test the visitor was never exposed to.

**Do this instead:** keep the container unconditional, and put the condition *inside* it — either inside the default content or inside each variant component, which are ordinary pages and can use `@if` / `<template-if>` freely. If the whole conditional block is the thing you want to test, make the block itself the container.

## Wrong vs right

Here is the mistake this page exists for, and what each error costs.

```html theme={null}
<!-- WRONG — three different layers glued together -->
<template-if data-condition="quizStep === 0">
  <div class="quiz-card">
    <split-test id="intro-hook" name="Quiz Intro Hook">
      <template-component data-component-name="quiz-intro-a"></template-component>
      <template-component data-component-name="quiz-intro-b"></template-component>
    </split-test>
  </div>
</template-if>
```

| # | Error | What actually happens |
| - | - | - |
| 1 | `<template-component>` is not implemented by any engine | Both elements render as empty unknown tags. The container's default content is **blank**. If the split test is ever paused or removed, the slot renders nothing at all. |
| 2 | Two variants written inline in one container | They are not variants — they are one default. The graph is the only thing that can choose between alternatives, and it never sees these. |
| 3 | The container is nested inside `<template-if>` | The variant is selected and the visitor enrolled on **every** request, including the ones where `quizStep !== 0` and the card is removed from the DOM before it paints. |

### Right — split-test the intro

```html theme={null}
<!-- In the page: the container is unconditional, and its content is a real default -->
<div class="quiz-card">
  <split-test id="intro-hook" name="Quiz Intro Hook">
    <h2>Answer 6 questions and we'll match you to a plan</h2>
    <p>Takes about 40 seconds.</p>
  </split-test>
</div>
```

Then in **Page Events**, wire the variants:

```text theme={null}
component_split_test { container: "intro-hook", value: 2 }
  ├─ split_test_weight { value: 50 } → component_split_test_component { component: "quiz-intro-a" }
  └─ split_test_weight { value: 50 } → component_split_test_component { component: "quiz-intro-b" }
```

`quiz-intro-a` and `quiz-intro-b` are saved components — each one is the complete replacement markup for that slot. Weights must total exactly 100.

### Right — gate the card on the quiz step

Move the condition inside, so the container is resolved unconditionally and only its *presentation* is conditional:

```html theme={null}
<div class="quiz-card">
  <split-test id="intro-hook" name="Quiz Intro Hook">
    <h2>Answer 6 questions and we'll match you to a plan</h2>
  </split-test>
</div>
```

…with the step logic living in the surrounding wizard rather than wrapped around the slot — or, if the card really must appear and disappear, put the `<template-if>` **inside** each variant component so every variant is enrolled and hidden on the same terms.

### Right — inline alternatives with no graph

When you want the alternatives in the page source and do not need component-level reporting:

```html theme={null}
<inline-split-test id="4821">
  <variant name="control" weight="50">
    <h2>Answer 6 questions and we'll match you to a plan</h2>
  </variant>
  <variant name="urgency" weight="50">
    <h2>40 seconds to your plan — start now</h2>
  </variant>
</inline-split-test>
```

### Right — a component include

```html theme={null}
{{-- Backend include: resolved during the template render --}}
@component("quiz-intro-a", { headline: "Start here" })
```

## Known gaps

Verified against the renderer. Flagged rather than papered over.

* **`<template-component>` is documented but unimplemented.** Several older reference tables list it as the frontend equivalent of `@component`. It is not — nothing resolves it. Use `@component("code")`.
* **Unbound containers can leak their wrapper tag.** See the note above; a fix is in progress.
* **The renderer matches container attributes in any order, but the builder's container scanner does not.** The Page Events container dropdown is populated by scanning for `id="…"` immediately followed by `name="…"`, both double-quoted. Written any other way the container still fills at runtime but cannot be selected in the UI. See [Dynamic content](/funnels/dynamic-content).

## Related

<CardGroup>
  <Card title="Backend template engine" href="/backend-template-engine/overview" />

  <Card title="Frontend template engine" href="/frontend-template-engine/overview" />

  <Card title="Page events" href="/funnels/page-events" />

  <Card title="Containers" href="/pages/containers" />

  <Card title="Dynamic content" href="/funnels/dynamic-content" />

  <Card title="Split testing" href="/funnels/split-testing" />
</CardGroup>


# SEO: sitemap.xml, robots.txt and llms.txt
Source: https://docs.elasticfunnels.io/pages/seo

Publish sitemap.xml, robots.txt and llms.txt for a brand, choose which pages they list, and pin the site to one https address with www/non-www redirects.

Every domain of a brand can serve three **discovery files**. They tell search
engines and AI crawlers which of your pages exist:

| File | What it is for |
| - | - |
| `/sitemap.xml` | One entry per listed page, with its last update date. Read by Google, Bing and other search engines. |
| `/robots.txt` | Crawl rules. Points crawlers at the sitemap and keeps them out of checkout and redirect paths. |
| `/llms.txt` | A plain-text index of the site that AI crawlers read to work out what the site is about ([llmstxt.org](https://llmstxt.org)). |

<Warning>
  **All three are off by default.** Until you turn them on, each path returns
  `404 Not found` on every domain of the brand. The same goes for listing a
  page: turning a file on doesn't list anything until you tick individual pages.
</Warning>

It's opt-in because most of a brand's pages are funnel steps, upsells and
checkouts. A sitemap that turned itself on would publish a map of all of them.

***

## Setting it up

<Steps>
  <Step title="Turn the files on for the brand">
    Go to **Settings → SEO**. Under **Discovery files**, switch on
    **Serve sitemap.xml**, **Serve robots.txt** and, if you want it,
    **Serve llms.txt**. Then click **Save**.

    Turn on robots.txt whenever you turn on the sitemap. robots.txt is what
    points crawlers at the sitemap, and without it most of them never find it.
  </Step>

  <Step title="Tick the pages you want listed">
    Open each public content page (home page, blog, articles, product and
    about pages), go to its **SEO** tab and tick
    **List this page in sitemap.xml and llms.txt**. Then save the page.
  </Step>

  <Step title="Check the preview">
    Back in **Settings → SEO**, the page list at the bottom shows exactly what
    the files contain right now. It runs the same rules as the live files. A
    page you ticked that still can't be listed shows a **Not listed** badge
    with the reason.
  </Step>

  <Step title="Verify on the live domain">
    Open `https://your-domain.com/sitemap.xml` and `/robots.txt`. Then submit
    the sitemap URL in Google Search Console.
  </Step>
</Steps>

***

## Setting it up with the `ef` CLI

The same setup works from the [`ef` CLI](https://www.npmjs.com/package/@elasticfunnels/cli)
(version 0.16.0 or later), run inside a folder linked to the brand.

```bash theme={null}
# 1. Turn the files on for the brand
ef seo set sitemap true
ef seo set robots true
ef seo set llms true            # optional

# 2. List pages, one at a time, by slug
ef pages settings pricing --sitemap
ef pages settings about --sitemap
ef pages settings pricing --no-sitemap   # remove one again

# 3. Check what the files contain
ef seo status
ef seo pages
```

`ef seo status` shows which files are on, how many pages are listed, and warns
when robots.txt is off or a page you ticked is excluded. `ef seo pages` prints
every page that opted in, the exact URL it publishes, and for each excluded
page, the reason.

### `ef seo` reference

| Command | What it does |
| - | - |
| `ef seo status` | Which files are served and how many pages they list. `--json` for scripts. |
| `ef seo pages` | The pages that opted in, their URLs, and `listed` / `NOT LISTED — <reason>`. |
| `ef seo get [key]` | Print every setting as `key=value`, or a single key's value on stdout. |
| `ef seo set <key> <value>` | Change one setting. |

| Key | Type | Admin label |
| - | - | - |
| `sitemap` | boolean | Serve sitemap.xml |
| `robots` | boolean | Serve robots.txt |
| `llms` | boolean | Serve llms.txt |
| `site-name` | text | Site name (llms.txt heading) |
| `site-summary` | text | Site summary (llms.txt) |
| `llms-notes` | text | Additional notes (llms.txt) |
| `robots-extra` | text | Additional directives (robots.txt) |

Booleans take `true`/`false`, `on`/`off`, `yes`/`no` or `1`/`0`. To clear a
text key, pass `""`:

```bash theme={null}
ef seo set site-name "Acme Supplements"
ef seo set site-summary "Direct-to-consumer supplements and guides."
ef seo set robots-extra "Disallow: /internal"
ef seo set llms-notes ""
```

While you're at it, `ef pages settings` can also set a page's SEO title and
meta description. llms.txt uses both:

```bash theme={null}
ef pages settings pricing --seo-title "Pricing" --seo-description "Plans and what each includes." --sitemap
```

<Note>
  The [site address](#site-address-www-non-www-and-https) settings (**Preferred
  domain** and **Redirect http to https**) are only in the admin, under
  **Settings → SEO**. The CLI doesn't set them yet.
</Note>

***

## Which pages are listed

A page appears in `sitemap.xml` and `llms.txt` only when **all** of these are
true:

* **List this page in sitemap.xml and llms.txt** is ticked on the page, or on
  one of its [variants](/pages/page-variants).
* The page is **published**.
* **Prevent Search Engine Indexing** is **off**.
* The page isn't a **checkout** or **upsell** page.
* It doesn't require **login** or a **password**.
* It isn't set to be visible only through a funnel.
* Its slug has no `{placeholder}`. A [wildcard route](/pages/wildcard-routes)
  stands for many URLs, not one.
* It belongs to the domain being requested (or its www/non-www twin), or it's
  a global page with no domain.

Each page is listed at the same URL as its `<link rel="canonical">`: `/` for
the index page, `/<slug>` for everything else. Variants are never listed
separately. The parent page stands for them. Each file lists at most 5,000
pages.

<Note>
  **Hiding a page:** turn on **Prevent Search Engine Indexing**. Don't add a
  `Disallow:` line for it. robots.txt is public, so a Disallow list is a
  directory of the pages you wanted hidden. It also stops crawlers from reading
  the page's `noindex` tag, so a page linked from somewhere else can still get
  indexed.
</Note>

***

## robots.txt

The generated file allows everything, blocks EF's system paths (checkout
processing, previews, redirect shims, `/affiliates/`, `/upsell*` and
`/decline*`), and ends with a `Sitemap:` line when the sitemap is on:

```text theme={null}
User-agent: *
Allow: /
Disallow: /process-checkout$
Disallow: /process-checkout?
...
Disallow: /upsell
Disallow: /decline

Sitemap: https://example.com/sitemap.xml
```

Each system path is anchored (`$`, `?`, `/`), so a rule like `/b` never blocks
a content page such as `/blogs`.

**Additional directives** (shown once robots.txt is on) adds your own lines
verbatim, one directive per line. Don't add a `Sitemap:` line. One is written
for you.

<Tip>
  If the domain is on Cloudflare with **Managed robots.txt** turned on, Cloudflare
  serves its own content-signals file when yours returns 404. Once you turn on
  **Serve robots.txt**, check the live file to see what Cloudflare adds to it.
</Tip>

***

## llms.txt

Shown once llms.txt is on:

| Field | Used as |
| - | - |
| **Site name** | The `#` heading. Defaults to the brand name. |
| **Site summary** | The `>` summary line. One or two sentences on what the site offers, and the first thing an AI crawler reads. |
| **Additional notes** | Free text added to the end: contact details, licensing, anything a crawler should know. |

Between the summary and the notes, each listed page becomes a link line, using
its SEO title and meta description:

```markdown theme={null}
# Example Store

> Handmade leather goods, shipped worldwide.

## Pages

- [Home](https://example.com/): Handmade leather wallets and bags.
- [About us](https://example.com/about)
```

***

## Site address: www, non-www and https

Search engines treat `www.example.com` and `example.com`, and `http` and
`https`, as four different sites. The **Site address** section picks one:

* **Preferred domain:** *Don't redirect*, *Without www* or *With www*. The
  other version gets a permanent **301** redirect to it. It only applies when
  **both** versions are added to the brand as domains. A domain with only one
  version is left alone.
* **Redirect http to https:** visitors and crawlers arriving over http get a
  301 to https.

Only `GET` and `HEAD` requests are redirected. Checkout and tracking `POST`s
are never redirected, because a browser replays a redirected POST as a GET and
loses the body. The path and query string carry over exactly, so affiliate
parameters arrive unchanged.

Whatever you choose here, `sitemap.xml`, `robots.txt`, `llms.txt` and every
page's canonical link always use **https** and the preferred domain.

***

## Canonical links

A page listed in the sitemap gets a `<link rel="canonical">` in its `<head>`
that points at its one address. There is only ever **one** canonical tag per
page:

* If your page's own HTML already declares a canonical (in its layout, its head
  code or **Custom header code**), ElasticFunnels adds none, and yours is the
  one search engines read. Make sure it points at your own domain.
* Otherwise ElasticFunnels adds it, using the same address the sitemap lists.

Pages that aren't listed in the sitemap get no canonical from ElasticFunnels.

### Your platform subdomain

Every brand has a free platform subdomain, such as `yourbrand.elasticfunnels.io`
or `yourbrand.elasticpages.co`. Pages without a domain of their own show on
**every** domain of the brand, so once you connect your own domain the
subdomain is an exact copy of your site. Search engines would count the copy as
duplicate content.

When your brand has its own domain, the platform subdomain handles this for you:

* Each shared page's canonical points at **your domain**
  (`https://yourdomain.com/about`, not `https://yourbrand.elasticfunnels.io/about`).
* Those pages are sent with an `X-Robots-Tag: noindex, follow` header. The copy
  drops out of search results, and links on it still count.
* On the subdomain, `/sitemap.xml` and `/llms.txt` redirect (301) to your
  domain's, and `/robots.txt` points at your domain's sitemap.

Your funnels, ads and links on the subdomain keep working exactly as before.
Only search engines are affected.

**Which domain is "yours":** the brand's only connected domain (`www.` and
non-www count as one). If the brand has several unrelated domains, set
**Settings → SEO → Primary domain**. Until you do, the subdomain keeps its own
address and stays indexable.

These are left alone:

* A brand with **no** domain of its own. The subdomain *is* the site, so it
  stays self-canonical and indexable.
* A page attached to the subdomain only. It exists nowhere else, so it keeps its
  own address.

***

## IndexNow: tell search engines about new pages

[IndexNow](https://www.indexnow.org) lets a site tell Bing, Yandex, Seznam,
Naver and other participating engines that a URL is new or has changed, instead
of waiting for them to crawl it. Google does not use IndexNow. Submit your
sitemap in Search Console for Google.

It's on for every brand that serves `sitemap.xml`:

1. When you publish a page listed in the sitemap, or change one (its address,
   content or listing), its address is queued.
2. Every 10 minutes the queue is sent in one batch per domain. If the engine is
   busy, it's retried later.
3. To prove the site is yours, your domain serves a key file at
   `https://yourdomain.com/<key>.txt`. The key is created automatically the
   first time something is sent.

Only addresses on **your own domain** are sent. Pages on the platform subdomain
never are.

To turn it off, switch off **Notify search engines on publish (IndexNow)** in
**Settings → SEO**.

***

## Caching

Crawlers get the files with a one-hour `Cache-Control`. Saving a page or the
brand's settings clears the server-side copy right away, so a newly ticked
page shows up on the next fetch. If you still see an old copy, it's coming
from Cloudflare or the browser cache.

## Troubleshooting

| Symptom | Cause |
| - | - |
| `/sitemap.xml` returns `404 Not found` | **Serve sitemap.xml** is off for the brand that owns this domain (`ef seo set sitemap true`). |
| The sitemap loads but has no `<url>` entries | No page has **List this page…** ticked, or every ticked page is excluded. The preview in **Settings → SEO**, or `ef seo pages`, shows why. |
| A page you ticked is missing | See [Which pages are listed](#which-pages-are-listed). The **Not listed** badge gives the reason. |
| robots.txt has no `Sitemap:` line | The sitemap is off. The line only appears when the sitemap is actually served. |
| URLs use the wrong www/non-www host | Set **Preferred domain**, and make sure both versions are added to the brand. |
| The subdomain still shows up in search | It has to be recrawled before the `noindex` takes effect, which can take weeks. If the brand has several domains, set **Primary domain**. Without it the subdomain stays indexable. |
| Two canonical tags on a page | Can't happen any more: when your HTML declares one, ElasticFunnels adds none. If you see two, both come from your own layout or header code. |


# Content Visibility Control
Source: https://docs.elasticfunnels.io/pages/visitor-based-content

Control which visitors can see specific content on your pages

Content Visibility Control allows you to show different content to different visitors based on their whitelisting status. This is useful for personalizing experiences, protecting sensitive content from competitors, and showing appropriate content to different visitor segments.

<CardGroup>
  <Card title="Whitelisted Container" icon="eye">
    Contains full content visible only to whitelisted visitors (VSL, sales pages, etc.)
  </Card>

  <Card title="Non-Whitelisted Container" icon="eye-slash">
    Contains standard content visible to all non-whitelisted visitors (TSL, basic info)
  </Card>
</CardGroup>

## How It Works

Content Visibility Control uses a whitelisting system to determine which visitors see which content. When a visitor is whitelisted, they see the full content in Whitelisted Containers. Non-whitelisted visitors see the standard content in Non-Whitelisted Containers.

<Info>
  Both container types can exist on the same page. The system automatically shows the appropriate container based on the visitor's whitelist status.
</Info>

## Content Containers

### Whitelisted Container

The **Whitelisted Container** displays content exclusively to whitelisted visitors.

**Features:**

* Contains **full content** (VSL, sales pages, complete offers)
* Only visible to whitelisted visitors
* Used for personalized visitor experiences
* Perfect for protecting sensitive information

**Use Cases:**

* Full sales presentations
* Complete product details
* Exclusive offers and pricing
* Detailed testimonials and case studies

### Non-Whitelisted Container

The **Non-Whitelisted Container** displays standard content to visitors who aren't whitelisted.

**Features:**

* Contains **standard content** (TSL, basic landing pages)
* Always visible to non-whitelisted visitors
* Default content for visitors without whitelist status
* Ensures all visitors see appropriate content

**Use Cases:**

* Basic landing pages
* General information
* Standard pricing displays
* Simplified content versions

## Content Display Methods

Choose the method that best fits your needs:

<CardGroup>
  <Card title="Container-Based" icon="layout" href="#container-based-display">
    **Recommended** - Use both containers on the same page for easy management
  </Card>

  <Card title="Page Loading" icon="file" href="#page-loading-method">
    Load entirely different pages based on visitor status
  </Card>

  <Card title="Redirect Method" icon="arrow-right" href="#redirect-method">
    Redirect users to different URLs based on their status
  </Card>
</CardGroup>

### Container-Based Display

<Note>
  This is the recommended method for most use cases.
</Note>

Use Whitelisted and Non-Whitelisted containers on the same page:

**Benefits:**

* ✅ Both versions exist on the same URL
* ✅ Easy to understand and manage
* ✅ Clear separation of standard vs full content
* ✅ No confusion about redirect destinations
* ✅ Better SEO and link management

**Setup Steps:**

1. **Add Whitelisted Container** to your page
2. **Add your full content** (VSL, sales copy, etc.) inside this container
3. **Add Non-Whitelisted Container** to your page
4. **Add standard content** (TSL, basic info) inside this container
5. **Configure whitelisting rules** in Page Events (see Whitelisting section below)

### Page Loading Method

Load entirely different pages based on visitor status:

**When to use:**

* Completely different page layouts needed
* Complex content differences
* Multiple page variants
* Different design systems per visitor type

**Setup:**

1. Create separate pages for different visitor segments
2. Use **"Load Page"** node in Page Events
3. Connect to query parameter conditions

<Tip>
  This method is useful when you need dramatically different layouts or when managing multiple page variants.
</Tip>

### Redirect Method

Redirect users to different URLs based on their status:

**When to use:**

* External landing pages
* Different domains for different content
* Integration with existing systems
* Third-party platform requirements

**Setup:**

1. Configure redirect rules in Page Events
2. Use **"Redirect to URL"** node
3. Connect to whitelisting conditions

## Whitelisting Visitors

Whitelisting determines which visitors see full content. There are three main methods:

<CardGroup>
  <Card title="Domain-Level" icon="globe" href="#domain-level-whitelisting">
    Automatically whitelist all visitors to a specific domain
  </Card>

  <Card title="Query Parameter" icon="link" href="#query-parameter-whitelisting">
    Whitelist visitors based on URL parameters (most common)
  </Card>

  <Card title="Session-Based" icon="clock" href="#session-based-whitelisting">
    Whitelisting persists across page navigation
  </Card>
</CardGroup>

### Domain-Level Whitelisting

Automatically whitelist all visitors to a specific domain:

**Setup:**

1. Go to **Domains** → **Edit Domain**
2. Enable **"Whitelist all visitors"**
3. All visitors to this domain will automatically see full content

**Use case:** When you have a separate domain for different visitor segments or traffic sources

**Example:**

* `main-site.com` - Whitelisted (shows full content)
* `review-site.com` - Non-whitelisted (shows standard content)

### Query Parameter Whitelisting

<Note>
  This is the most common method for whitelisting visitors.
</Note>

Whitelist visitors based on URL parameters:

**Setup Steps:**

1. Go to **Page Events** for the specific page you want to configure
2. From the **"On Page Loaded"** node, drag a new **"Query Parameter Condition"** node
3. Configure the parameter you want to check (e.g., `vtID` equals `k`)
4. From the **"Query Parameter Condition"** node, drag a **"Whitelist Visitor"** node
5. Visitors with the correct parameter will be whitelisted for their entire session

**Example URL:**

```
https://yoursite.com/page?vtID=k
```

**Common Parameters:**

* `vtID=k` - General whitelisting
* `access=premium` - Premium content access
* `preview=true` - Preview mode

<Tip>
  You can also use **"Mark Visitor as Not Whitelisted"** to remove whitelist status under specific conditions.
</Tip>

### Session-Based Whitelisting

Once a visitor is whitelisted, they remain whitelisted for their entire session:

**Features:**

* **Persistent:** Whitelisting survives page navigation
* **Session-wide:** Applies to all pages in the funnel
* **Automatic:** No need to re-whitelist on each page
* **Cookie-based:** Uses session cookies to maintain status

**How it works:**

1. Visitor arrives with whitelisting parameter
2. System whitelists visitor for the session
3. Visitor navigates to other pages
4. Whitelist status persists automatically
5. Status expires when session ends

## Advanced Whitelisting Scenarios

### Conditional Whitelisting

Use **"Mark visitor as not whitelisted"** if you need to:

* Remove whitelist status under certain conditions
* Require the parameter on every page visit
* Reset whitelisting for testing
* Create time-limited access

**Example Flow:**

```
Page Load → Query Parameter (vtID=k) → Whitelist Visitor
         → Query Parameter (reset=true) → Mark as Not Whitelisted
```

### Multiple Whitelisting Methods

You can combine different whitelisting methods for complex scenarios:

**Combinations:**

* Domain-level + Query parameters
* Different parameters for different content
* Conditional logic based on traffic source
* Geographic-based whitelisting

**Example:**

```
Domain: main-site.com (auto-whitelisted)
  → Query Parameter (source=partner) → Additional premium content
  → Query Parameter (source=competitor) → Mark as Not Whitelisted
```

## Best Practices

### Content Strategy

<CardGroup>
  <Card title="Content Quality">
    Keep standard content functional and valuable - ensure it provides real value to visitors
  </Card>

  <Card title="Layout Consistency">
    Maintain similar layout between versions when possible for better user experience
  </Card>

  <Card title="Testing">
    Test both versions regularly to ensure they work correctly
  </Card>

  <Card title="Performance">
    Consider loading speed - avoid bloated containers that slow down pages
  </Card>
</CardGroup>

### Implementation Tips

* **Use descriptive container names** for easy identification in the page builder
* **Test whitelisting logic** thoroughly before going live
* **Monitor both versions** for performance and functionality
* **Document your whitelisting rules** for team members
* **Use consistent parameter names** across all pages

### Platform Compliance

* **Follow platform policies** - ensure all content meets platform requirements
* **Keep content relevant** - both versions should accurately represent your offering
* **Use responsibly** - content visibility control should enhance user experience, not mislead
* **Review platform terms** regularly as they change

<Warning>
  Content Visibility Control should be used responsibly and in accordance with all platform terms of service. Ensure all content meets platform requirements and accurately represents your offering.
</Warning>

## Troubleshooting

### Common Issues

<CardGroup>
  <Card title="Whitelisting Not Working">
    **Solution:** Check query parameter spelling and case sensitivity. Parameters are case-sensitive.
  </Card>

  <Card title="Content Not Switching">
    **Solution:** Verify container names and Page Events connections. Check browser console for errors.
  </Card>

  <Card title="Session Issues">
    **Solution:** Clear browser cache and cookies for testing. Test in incognito mode.
  </Card>

  <Card title="Parameter Not Recognized">
    **Solution:** Ensure the parameter is set correctly in Page Events and matches the URL exactly.
  </Card>
</CardGroup>

### Testing Your Setup

Follow these steps to verify your Content Visibility Control setup:

1. **Test Standard Content**
   * Visit your page without whitelisting parameter
   * Should see standard content (Non-Whitelisted Container)

2. **Test Full Content**
   * Add the whitelisting parameter to URL (e.g., `?vtID=k`)
   * Should see full content (Whitelisted Container)

3. **Test Session Persistence**
   * Navigate to other pages in the funnel
   * Should remain whitelisted across pages

4. **Test in Incognito Mode**
   * Verify session behavior without cached data
   * Test parameter recognition

<Tip>
  Use browser developer tools to inspect cookies and session data when troubleshooting whitelisting issues.
</Tip>

## Related Documentation

<CardGroup>
  <Card title="Page Events" icon="code" href="/funnels/page-events">
    Learn how to set up whitelisting logic with Page Events
  </Card>

  <Card title="Query Parameters" icon="link" href="/funnels/query-parameters">
    Understand how to use URL parameters for whitelisting
  </Card>

  <Card title="Containers" icon="layout" href="/pages/containers">
    Learn about all available container types
  </Card>

  <Card title="Domain Whitelisting" icon="globe" href="/domains/whitelisting">
    Set up domain-level whitelisting
  </Card>
</CardGroup>


# Wildcard routes
Source: https://docs.elasticfunnels.io/pages/wildcard-routes

Serve many URLs from one page by putting {placeholders} in its slug, then read the captured segments as route_params in templates and backend scripts.

A **wildcard route** lets one page answer many URLs. You put `{placeholders}`
in the page's slug, and every URL that fits the pattern renders that page with
the URL's segments handed to your template as **`route_params`**.

One "guided course" page can then serve
`/app/guided-courses/foundations/module-1`,
`/app/guided-courses/advanced/lesson-5`, and every other course and module.

<Note>
  **Prefer a wildcard route over a query string.** For product, course, article
  and category detail pages, `/shop/product/blue-widget` beats
  `/shop/product?id=42` on every axis that matters — see
  [Use paths, not `?id=`](#use-paths-not-id) below.
</Note>

***

## How a URL is matched

When a request arrives, the runtime resolves it in three steps and stops at
the first hit:

1. **Exact slug.** A page whose slug is literally the requested path.
2. **Wildcard patterns.** Pages whose slug contains `{…}`, tried
   **longest URL prefix first**.
3. **Folder index.** `/<path>` and `/<path>/` fall back to a page saved as
   `<path>/index`. This is a last resort, so `ecom/{slug}` still wins over
   `ecom/index` for `/ecom/cart`.

A pattern matches only when **both** of these hold:

* Its **static prefix** — everything before the first `{` — is exactly the URL
  prefix being tested.
* Its **number of placeholders** equals the number of segments left over.

A page whose slug has no braces is never wildcard-matched. A plain page at
`app` will not catch `/app/anything`; only `app/{slug}` will.

***

## Setting up a wildcard route

### 1. Create the page

Give the page a slug that contains the placeholders, e.g.

```
app/guided-courses/{course}/{module}
```

* **Fixed part:** `app/guided-courses`
* **Dynamic parts:** `{course}` and `{module}`

```bash theme={null}
ef pages create "app/guided-courses/{course}/{module}"
```

### 2. What matches

| URL | `route_params.course` | `route_params.module` |
| - | - | - |
| `/app/guided-courses/foundations/module-1` | `foundations` | `module-1` |
| `/app/guided-courses/advanced/lesson-5` | `advanced` | `lesson-5` |
| `/app/guided-courses/intro/welcome` | `intro` | `welcome` |

<Warning>
  The bare prefix `/app/guided-courses` does **not** match this page — two
  placeholders require exactly two trailing segments. If you want a landing page
  at the prefix, create a separate page with the slug `app/guided-courses` or
  `app/guided-courses/index`.
</Warning>

***

## Rules and limits

**Placeholders must all be trailing.** The static prefix stops at the first
`{`, so any literal segment written *after* a placeholder is ignored when
matching:

| Slug | Behaves as | Matches | Does **not** match |
| - | - | - | - |
| `blog/{slug}` | prefix `blog`, 1 param | `/blog/hello` | `/blog/2024/hello` |
| `blog/{cat}/posts/{id}` | prefix `blog`, 2 params | `/blog/tech/5` | `/blog/tech/posts/5` |

To keep a literal segment in the middle, put it in the fixed part instead:
`blog/tech/posts/{id}`.

**A slug cannot start with a placeholder.** Matching always tests at least one
literal leading segment, so a slug like `{hl}/about` never matches any URL.
Start the pattern with a real segment (`docs/{topic}`).

**Sibling patterns are disambiguated by prefix.** `blog/{slug}` and
`blog/category/{slug}` can coexist: `/blog/hello` picks the first,
`/blog/category/news` picks the second, because each pattern's static prefix
must equal the URL prefix exactly.

**Offline and deleted pages are skipped**, and at most 50 candidate patterns
are considered per prefix.

**Wildcard pages are never listed in [`sitemap.xml` or `llms.txt`](/pages/seo)** — a
`{param}` slug stands for many URLs, not one. Link to concrete URLs from a
listing page you *do* publish.

***

## Reading the segments

Two values are available once a wildcard route matches:

* **`route_params`** — an object keyed by your placeholder names, e.g.
  `{ course: 'foundations', module: 'module-1' }`.
* **`route_slug`** — the whole remainder as one string, e.g.
  `foundations/module-1`.

Both are `null` when the page was reached by an exact slug, the domain index,
or the folder-index fallback.

<Note>
  The keys of `route_params` are always your placeholder names. There is no
  `segment_0` / `segment_1` — name the placeholder whatever you want to read
  (`{slug}` → `route_params.slug`).
</Note>

### In a template

```html theme={null}
<p>Course: {{ route_params.course }}</p>
<p>Module: {{ route_params.module }}</p>
```

### In a backend script

`route_params` arrives on the request object:

```js theme={null}
// efmeta:{...}
const { course, module } = request.route_params || {};
```

### Guarding

On a non-wildcard URL `route_params` is null, so guard before reading it:

```html theme={null}
@if(route_params and route_params.course)
  @set(course = getCourseBySlug(route_params.course))
@endif
```

***

## Use paths, not `?id=`

For any page that renders **one of many** records — a product, a course, a
blog post, a category — put the identifier in the **path** via a wildcard
route rather than in a query string.

| | Wildcard route | Query string |
| - | - | - |
| URL | `/shop/product/blue-widget` | `/shop/product?code=blue-widget` |
| Indexed by search engines | Yes, as distinct pages | Usually collapsed to one URL |
| Shareable / readable | Yes | Poorly |
| Analytics | One row per product | One row for every product |
| Cacheable at the edge | Yes | Query strings often bypass the cache |
| Ad platforms | Clean destination URLs | Params get stripped or rewritten |

Query strings still make sense for things that **modify** a view rather than
identify it: `?page=2`, `?sort=price`, `?hl=en`, and UTM tags.

### Product detail pages

Build the page once with a placeholder:

* **Page slug:** `shop/product/{code}`
* **Template:**

  ```html theme={null}
  @set(product = getProduct(route_params.code))
  @if(product)
    <h1>{{ product.title }}</h1>
    <p>{{ product.price | formatPrice:product.currency }}</p>
  @endif
  ```

`getProduct()` accepts a product **id or code**, so the segment can be either.

Link to it from your catalog with the **`productUrl`** filter, which emits
`/<base>/<slug>-<id>`:

```html theme={null}
@foreach(product in getProducts())
  <a href="{{ product | productUrl:'shop/product' }}">{{ product.title }}</a>
@endforeach
```

That produces `/shop/product/blue-widget-42`, so pair it with the slug
`shop/product/{handle}` and split the trailing id in a backend script:

```js theme={null}
const handle = (request.route_params || {}).handle || '';
const id = handle.split('-').pop();
```

See [Products and shipping](/backend-template-engine/products-and-shipping)
for the full product API.

### Course detail pages

* **Page slug:** `app/guided-course/{course}`
* **Template:**

  ```html theme={null}
  @set(course = getCourseBySlug(route_params.course))
  @if(course)
    <h1>{{ course.title }}</h1>
  @endif
  ```

`getCourseBySlug()` also falls back to the URL on its own when you call it
with no argument: it reads `?slug=`, then `route_params.course`, then
`route_slug`. Passing the value explicitly is clearer, and required when your
placeholder is named anything other than `course`.

***

## Examples

### One placeholder — record by slug

* **Page slug:** `app/guided-course/{slug}`
* **URLs:** `/app/guided-course/foundations`, `/app/guided-course/advanced`
* **In template:** `route_params.slug` (or `route_slug`, same value here)

### Two placeholders — course + module

* **Page slug:** `app/guided-courses/{course}/{module}`
* **URLs:** `/app/guided-courses/foundations/module-1`
* **In template:** `route_params.course`, `route_params.module`

### Three placeholders

* **Page slug:** `learn/{topic}/{level}/{lesson}`
* **URL:** `/learn/javascript/beginner/01-variables`
* **In template:** `route_params.topic`, `route_params.level`,
  `route_params.lesson`

***

## Summary

| You want… | Page slug | In template |
| - | - | - |
| One dynamic segment | `shop/product/{code}` | `route_params.code` |
| Named segments | `app/guided-courses/{course}/{module}` | `route_params.course`, `route_params.module` |
| The whole remainder as one string | any wildcard page | `route_slug` |
| A landing page at the prefix | `shop/product` or `shop/product/index` | — |

Use **`{name}`** in the slug for each dynamic part, then read
**`route_params.name`** (or **`route_slug`**) in the template or
`request.route_params` in a backend script.

## Related

* [Products and shipping](/backend-template-engine/products-and-shipping) —
  `productUrl`, `getProduct`, and the product fields to render.
* [Internationalization (i18n)](/pages/internationalization) — `route_params.hl`
  and `route_params.locale` are the highest-priority locale hints, ahead of
  `?hl=`.
* [Rendering pipeline](/pages/rendering-pipeline) — where route resolution sits
  relative to the template engines.


# Advanced Purchase Links
Source: https://docs.elasticfunnels.io/products/advanced-purchase-links

Insert product purchase links from the page builder without typing product codes by hand

Use advanced purchase links to add buy buttons from the page builder without typing product codes by hand.

## Enhanced Link Insertion

### Product Dropdown

Select products from a dropdown instead of typing product codes:

1. **Select a link element** in your page builder
2. **Click "Insert Product Purchase Link"** in the properties panel
3. **Choose from dropdown** - All defined products appear in the list
4. **Generated link** - ElasticFunnels creates the correct buy link
5. **Instant preview** - See the link format immediately

### Benefits of Dropdown Selection

* **No manual typing** - Eliminates typos in product codes
* **Visual product selection** - See product names and details
* **Automatic formatting** - Correct link syntax generated automatically
* **Consistent codes** - Ensures all links use the same product identifiers
* **Quick updates** - Change products without remembering codes

## Link Types and Formats

### Standard Purchase Links

**Generated format**: `[BUY=product_code]`

* Used for main product purchases
* Integrates with your configured payment gateway
* Automatically includes funnel settings (like CBFID)

### Upsell Links

**Generated format**: `[UPSELL=product_code]`

* Used for upsell and cross-sell offers
* Maintains purchase context from previous transaction
* Optimized for post-purchase flows

### Decline Links

**Generated format**: `[DECLINE]`

* Used for "No thanks" or decline buttons
* Automatically generated for upsell pages
* Tracks declination rates for optimization

### Subscription Modification Links

**Generated formats**: `[UPSELL_UPGRADE=old_sku, new_sku]` and `[UPSELL_CANCEL]`

* Used for modifying existing subscriptions mid-funnel
* Executes an API call instead of redirecting to checkout
* Available for ClickBank and NMI merchants
* See [Subscription Upsells](/products/subscription-upsells) for full documentation

## Product Integration

### Product Definition Requirements

Before using the dropdown system, ensure you have:

1. **Products defined** in the Products section
2. **Product codes assigned** - Each product needs a unique code
3. **Pricing configured** - Set up your pricing structure
4. **Merchant integration** - Connected to your payment processor

### Product Organization

**Best practices for product management**:

* **Descriptive names** - Use clear, recognizable product names
* **Consistent codes** - Use logical naming conventions for codes
* **Category grouping** - Organize products by type or campaign
* **Regular updates** - Keep product list current and clean

## Advanced Link Features

### Automatic Parameter Addition

The system automatically adds relevant parameters:

* **CBFID integration** - Automatically includes ClickBank pitch flow ID
* **Affiliate tracking** - Adds affiliate parameters when applicable
* **Campaign data** - Includes campaign tracking information
* **Custom attributes** - Adds product-specific parameters

### Dynamic Link Generation

Links adapt based on context:

* **Funnel settings** - Uses the funnel's configured payment gateway
* **Domain settings** - Applies domain-specific merchant settings
* **Visitor data** - Includes relevant visitor tracking information
* **Split test variants** - Adjusts based on active split tests

## Examples

### Basic Product Page

```html theme={null}
<!-- Before: Manual typing -->
<a href="[BUY=supplement_3_bottles]">Buy 3 Bottles</a>

<!-- After: Dropdown selection -->
Select link → Insert Product Purchase Link → Choose "3 Bottle Supplement Pack"
Result: <a href="[BUY=supplement_3_bottles]">Buy 3 Bottles</a>
```

### Upsell Page

```html theme={null}
<!-- Upsell offer -->
<a href="[UPSELL=supplement_6_bottles]">Upgrade to 6 Bottles</a>

<!-- Decline option -->
<a href="[DECLINE]">No Thanks</a>
```

### Multiple Product Options

```html theme={null}
<!-- Different variants on same page -->
<a href="[BUY=supplement_1_bottle]">1 Bottle - $49</a>
<a href="[BUY=supplement_3_bottles]">3 Bottles - $127</a>
<a href="[BUY=supplement_6_bottles]">6 Bottles - $197</a>
```

## Integration with Existing Systems

### ClickBank Integration

* **Automatic CBFID inclusion** - No need to manually add pitch flow IDs
* **Product variant support** - Works with multiple product options
* **Affiliate tracking** - Maintains affiliate attribution through purchase flow

### Other Payment Gateways

* **Merchant-specific formatting** - Adapts to your configured gateway
* **Parameter optimization** - Includes gateway-specific requirements
* **Fallback handling** - If a gateway-specific link cannot be generated, the page shows a clear error

## Best Practices

### Link Organization

* **Use descriptive anchor text** - Clear call-to-action text
* **Consistent styling** - Maintain visual consistency across all buy buttons
* **Strategic placement** - Position links where they make sense in the flow
* **Mobile optimization** - Ensure links work well on all devices

### Product Management

* **Regular audits** - Review and clean up unused products
* **Version control** - Keep track of product changes and pricing updates
* **Test thoroughly** - Verify all links work correctly after updates
* **Documentation** - Maintain records of product codes and their purposes

### Performance Optimization

* **Minimize redirects** - Use direct links when possible
* **Fast loading** - Optimize for quick page and checkout loading
* **Error handling** - Provide clear error messages for failed purchases
* **Analytics tracking** - Monitor link performance and conversion rates

## Troubleshooting

### Common Issues

* **Product not appearing in dropdown** - Check that product is properly defined
* **Link not working** - Verify product code and merchant configuration
* **Wrong pricing displayed** - Check product pricing configuration
* **Affiliate tracking missing** - Ensure affiliate parameters are properly configured

### Testing Your Links

1. **Preview mode** - Test links in preview before publishing
2. **Test purchases** - Use test mode to verify complete purchase flow
3. **Cross-browser testing** - Ensure links work in all major browsers
4. **Mobile testing** - Verify mobile purchase experience
5. **Analytics verification** - Confirm tracking is working correctly

### Debugging Steps

1. **Check product configuration** - Verify all product details are correct
2. **Verify merchant settings** - Ensure payment gateway is properly configured
3. **Test link generation** - Use the dropdown to regenerate links
4. **Monitor console** - Check for JavaScript errors in browser console
5. **Review analytics** - Look for patterns in failed purchases

## Migration from Manual Links

### Updating Existing Links

1. **Identify manual links** - Find all manually typed purchase links
2. **Use dropdown replacement** - Replace with dropdown-generated links
3. **Test thoroughly** - Verify all links still work after replacement
4. **Update documentation** - Record changes for future reference

### Benefits of Migration

* **Reduced errors** - Eliminate typos in product codes
* **Easier maintenance** - Update products in one place
* **Better tracking** - Improved analytics and conversion tracking
* **Easier updates** - Easier to adapt when products or gateway settings change

## Advanced Customization

### Custom Link Parameters

You can still add custom parameters to generated links:

```html theme={null}
<!-- Generated base link -->
[BUY=product_code]

<!-- With custom parameters -->
[BUY=product_code extra=campaign_data source=email]
```

### Dynamic Link Modification

Use Page Events to modify links dynamically:

* **Conditional parameters** - Add parameters based on visitor data
* **A/B testing** - Test different link variations
* **Personalization** - Customize links based on user preferences
* **Campaign tracking** - Add campaign-specific parameters

<Note>
  Use the dropdown to avoid typos in product codes.
</Note>


# Buy Links
Source: https://docs.elasticfunnels.io/products/buy-links

Add purchase links to enable direct product sales from your pages

Buy links let customers purchase products directly from your page.

## Add a Product

### Step 1: Create Product

1. Go to "Products" → "Add Product"
2. Fill out all necessary information and define a product code
3. Include cost of goods if you want reporting

### Step 2: Embedding the Buy Link

1. Create a link tag and insert `[BUY=product_code]` or `[UPSELL=product_code]`
2. You can pass more data, e.g., `[BUY=product_code extra=abcd]`

### Step 3: Merchant Information

1. If you have a different code on Buygoods, Clickbank, or Digistore24, go to the "Merchant Information" tab
2. Associate the correct product ID from that platform

## Buy Link Formats

### Basic Buy Link

```
[BUY=your_product_code]
```

### Upsell Link

```
[UPSELL=your_product_code]
```

### Advanced Parameters

```
[BUY=product_code extra=campaign_data]
```

## Parameter Options

### Standard Parameters

* **extra**: Additional tracking data
* **quantity**: Pre-set purchase quantity
* **discount**: Apply discount codes

### Platform-Specific Affiliate Parameters

Affiliate parameters are typically passed via URL query strings to the landing page, not in buy links. The system automatically captures and tracks them:

* **ClickBank**: `hop` or `affiliate` (affiliate ID), `tid` (tracking ID/sub-affiliate)
* **Buygoods**: `aff_id` (affiliate ID), `subid` (sub-affiliate tracking)
* **Digistore24**: `aff` (affiliate ID)

<Note>
  **CBFID** (ClickBank Pitch Flow ID) is configured at the funnel level and automatically included in purchase links. You don't need to add it manually to buy links.
</Note>

## Product Setup Best Practices

### Required Information

* Clear product name and description
* Accurate pricing information
* Product code (keep it simple and memorable)
* High-quality product images

### Optional but Recommended

* Cost of goods sold (for profit tracking)
* Product categories and tags
* Shipping information
* Return/refund policy

## Troubleshooting Buy Links

### Common Issues

* **Link not working**: Verify product code spelling
* **Wrong price showing**: Check merchant platform settings
* **Affiliate tracking missing**: Ensure proper parameter format
* **Payment processing errors**: Verify merchant account status

### Testing Your Links

* Test purchase flow from start to finish
* Verify affiliate tracking is working
* Check that confirmation emails are sent
* Ensure proper redirect after purchase

## Related Documentation

* [Upsells](/products/upsells) — Post-purchase one-click upsells within a funnel
* [QuickBuy (Card on File)](/products/quickbuy) — Charge returning customers with their stored card, no checkout needed
* [Advanced Purchase Links](/products/advanced-purchase-links) — Generated link formats and examples


# Custom Product Attributes (Legacy)
Source: https://docs.elasticfunnels.io/products/custom-attributes

Add unstructured key/value metadata to products — legacy system, see Product Attributes for the typed replacement

> **Note:** Custom Attributes are a legacy system for unstructured key/value pairs. For typed, reusable, filterable attributes, use [Product Attributes](/products/product-attributes) instead. Both systems can coexist on the same product.

Custom attributes let you store arbitrary key/value metadata on a product (e.g., a bonus download URL, warranty info, or an affiliate-specific value) without needing a formal attribute definition.

## Create Custom Attributes

### Step 1: Add Attributes to Product

1. In "Products," select or create the product
2. Click the **Custom Attributes** tab
3. Add a new key/value pair (e.g., `bonus_url` → `https://yourbonuslink`)
4. Save your changes

### Step 2: Use in Page Builder

1. Add a "Product Item" component to your page
2. In the properties tab, configure fields such as Product Type and Classification (e.g., Bonus)
3. To display attributes, add text or links using `{product.attributes.[attribute_name]}`, e.g., `{product.attributes.bonus_url}`

## Common Attribute Types

### Bonus Content

* **bonus\_url**: Link to bonus materials
* **bonus\_description**: Description of bonus content
* **bonus\_value**: Monetary value of bonuses

### Product Details

* **warranty\_period**: Product warranty information
* **shipping\_weight**: For shipping calculations
* **dimensions**: Product size specifications
* **color\_options**: Available color variants

### Marketing Data

* **launch\_date**: When product was released
* **bestseller\_rank**: Ranking information
* **testimonial\_count**: Number of reviews/testimonials
* **guarantee\_terms**: Money-back guarantee details

## Display Attributes on Pages

### Text Display

```
Bonus Value: {product.attributes.bonus_value}
```

### Link Display

```html theme={null}
<a href="{product.attributes.bonus_url}">Download Your Bonus</a>
```

### Conditional Display

Show attributes only if they exist:

```
{if product.attributes.warranty_period}
  Warranty: {product.attributes.warranty_period}
{endif}
```

## Advanced Use Cases

### Dynamic Pricing

* Store different price points for different audiences
* Show member vs. non-member pricing
* Regional pricing variations

### Affiliate-Specific Content

* Custom bonuses per affiliate
* Affiliate-specific landing page content
* Tracking codes and parameters

### Seasonal Promotions

* Holiday-specific offers
* Limited-time bonus content
* Seasonal product variations

## Best Practices

### Naming Conventions

* Use descriptive, consistent attribute names
* Avoid spaces (use underscores: `bonus_url` not `bonus url`)
* Keep names lowercase for consistency

### Data Management

* Regularly audit and clean up unused attributes
* Document what each attribute is used for
* Maintain consistency across similar products

### Performance Considerations

* Don't create excessive attributes for single products
* Use attributes efficiently to avoid page slowdowns
* Cache frequently accessed attribute data

## Troubleshooting

### Common Issues

* **Attribute not displaying**: Check spelling and syntax
* **Broken links**: Verify URLs in attribute values
* **Missing data**: Ensure attributes are saved to the product
* **Formatting problems**: Check for special characters in attribute values


# Product Attributes
Source: https://docs.elasticfunnels.io/products/product-attributes

Create reusable, typed brand-level attributes (Color, Material, Scent, etc.) and assign values per product or variant

Product Attributes are brand-level, reusable field definitions that you can apply across all products. Unlike [Custom Attributes](/products/custom-attributes) (legacy unstructured key/value pairs), Product Attributes support rich field types, filtering, storefront visibility, and variant-level scoping.

## Managing Attribute Definitions

Go to **Settings → Products → Product Attributes** to create, edit, and reorder attribute definitions.

Each attribute definition has:

| Field | Description |
| - | - |
| **Name** | Display label (e.g. "Material", "Scent") |
| **Slug** | Auto-generated URL-safe key used in templates (e.g. `material`) |
| **Field Type** | See full type list below |
| **Applies To** | Where values are stored: Product, Variant, or Both |
| **Options** | For `select` and `multiselect` types: the allowed values |
| **Required** | Whether a value must be set before saving |
| **Filterable** | Available as a storefront/catalog filter |
| **Visible on Product Page** | Shown in the product page details section |

***

## Field Types

Product Attributes support the full set of CRM-style field types:

| Type | Input | Use Case |
| - | - | - |
| `text` | Single-line text | Short values (colour name, size label) |
| `textarea` | Multi-line text | Longer descriptions without formatting |
| `rich_text` | Rich text | Formatted content |
| `wysiwyg` | WYSIWYG editor | Full rich text editing |
| `email` | Email input | Contact or support email |
| `phone` | Phone input | Contact number |
| `url` | URL input | Product page, demo link |
| `number` | Number input | Weight, volume, count |
| `date` | Date picker | Release date, expiry date |
| `datetime` | Date & time picker | Event datetime |
| `boolean` | Checkbox (Yes/No) | Organic, Vegan, In stock |
| `select` | Dropdown | Single value from predefined options |
| `multiselect` | Checkboxes | Multiple values from predefined options |
| `color` | Color picker + text | Hex colour value |
| `image` | URL text input | Image URL |
| `file` | URL text input | File URL |
| `json` | Monospace textarea | Structured JSON data |

***

## Applies To Scoping

The `applies_to` field controls where attribute values are stored and edited:

| Value | Behaviour |
| - | - |
| `product` | Value is stored at the product level. Edited in the **Attributes** tab of the Product Detail Page. |
| `variant` | Value is stored per variant. Edited in the **Variants** tab per variant row (coming soon). |
| `both` | Product-level default, but can be overridden per variant. |

***

## Assigning Values to Products

Open any product and go to the **Attributes** tab. You will see all brand-level attribute definitions that apply to the product level. Fill in values and save.

Attributes with `applies_to = variant` are managed in the Variants tab, not the Attributes tab.

***

## Template Access

### List Definitions

```
{% set attrs = getProductAttributes() %}
{% for attr in attrs %}
  {{ attr.slug }}: {{ attr.name }} ({{ attr.type }})
{% endfor %}
```

Filter by scope or visibility:

```
{% set visibleAttrs = getProductAttributes({ visible: true, applies_to: 'product' }) %}
```

### Get Product Values

```
{% set vals = getProductAttributeValues(product) %}
{{ vals.material }}
{{ vals.scent }}
```

### Shorthand Filters

When a product is loaded via `getProduct()`, attribute values and definitions are pre-loaded:

```
{{ product | attr:'material' }}        — value by slug
{{ product | attrLabel:'material' }}   — display label by slug
```

### Full Display Example

```
{% set attrDefs = getProductAttributes({ visible: true }) %}
{% set attrVals = getProductAttributeValues(product) %}
<dl>
{% for def in attrDefs %}
  {% set val = attrVals[def.slug] %}
  {% if val %}
    <dt>{{ def.name }}</dt>
    <dd>{{ val }}</dd>
  {% endif %}
{% endfor %}
</dl>
```

***

## Relationship to Custom Attributes

[Custom Attributes](/products/custom-attributes) are legacy unstructured key/value pairs stored directly on the product. Product Attributes are the preferred system — typed, reusable, filterable, and scoped to product or variant level.

Both systems can coexist. Custom Attributes are available under the **Custom Attributes** tab; Product Attributes under the **Attributes** tab.


# Product Management
Source: https://docs.elasticfunnels.io/products/product-management

Create and manage products with full e-commerce data: SEO, gallery, inventory, variants, attributes, fulfillment, subscriptions and more

Each product has one detail page for pricing, checkout behavior, shipping, fulfillment, subscriptions, SEO, and custom data.

## Creating a Product

Click **Add Product** in the Products list to open the quick-create modal. Enter the essential fields (Title, Code, Type, Classification, Price) and click **Create product**. You are automatically taken to the full Product Detail Page to complete configuration.

## Product Detail Page

Navigate to the Product Detail Page by clicking any product code or title in the Products list.

The page uses a persistent tab layout. Changes are saved by clicking **Save** in the top toolbar.

***

### General Tab

Core product identity, titles, images, descriptions, category assignment, and SEO metadata.

| Field | Description |
| - | - |
| **Type** | Physical, Digital, or Service |
| **Code** | Unique identifier used in buy links (read-only after creation) |
| **Classification** | Main, Upsell, Downsell, Bump, or Bonus |
| **Status** | Active, Draft, or Archived |
| **Show in frontend** | On by default. Lists the product in shop and catalog pages. Turning it off hides it from `getProducts()` only, it still sells everywhere it is used. See [Storefront visibility](/backend-template-engine/products-and-shipping#storefront-visibility) |
| **Title** | Primary display name |
| **Checkout Title** | Overrides Title at checkout (optional) |
| **Product Image** | Primary product image — upload directly from this tab |
| **Gallery** | Additional product images — upload files directly or remove existing images via the visual thumbnail picker |
| **Short Description** | Brief summary for product cards and search results |
| **Full Description** | Rich text or plain text description |
| **Category / Subcategory** | Assign from brand-level product categories |
| **SEO Title** | Page title for search engines |
| **SEO Slug** | URL slug for storefront product pages |
| **SEO Description** | Meta description (max 160 chars) |

***

### Pricing Tab

Selling price, retail (compare-at) price, currency, and tax settings.

| Field | Description |
| - | - |
| **Retail Price** | Compare-at price shown as strikethrough |
| **Discounted Price** | Actual selling price |
| **Currency** | 3-letter currency code (e.g. USD) |
| **Tax Exempt** | When enabled, no tax is calculated at checkout |
| **Tax Category** | TaxJar TIC or Avalara tax code |

***

### Subscription Tab

Visible only when **This is a subscription product** is enabled. See [Subscriptions Overview](/subscriptions/overview) for full billing documentation.

| Field | Description |
| - | - |
| **Is Subscription** | Toggle to enable recurring billing |
| **Build-a-Box** | Customers select multiple items for their subscription box |
| **Billing Frequency** | How often to bill (e.g. 1) |
| **Frequency Unit** | Day / Week / Month / Year |
| **Trial Days** | Free trial days before first charge |
| **First Charge Free** | Customer pays shipping only on first order |
| **Subscription Tiers** | Multiple billing frequencies at different prices (toggle to enable) |
| **Subscribe & Save (%)** | Discount when customer chooses subscription over one-time purchase |
| **Stepped Pricing** | Different prices at specific billing cycles (toggle to enable) |
| **Prepaid Options** | 3, 6, 12-month prepaid discounts |

***

### Fulfillment Tab

Warehousing, inventory, cost breakdown, SKU categorisation, product specifications, and shipping profile.

| Section | Fields |
| - | - |
| **Identity & Structure** | SKU, Barcode, Units per Package, Weight (oz), Dimensions (L/W/H cm) |
| **Integration** | Fulfillment Integration override, Multiply SKU toggle |
| **Inventory** | Stock Quantity, Out-of-Stock Policy (continue/deny) |
| **Cost Breakdown** | Product Cost, Fulfillment Cost, Packaging Cost, Avg. Shipping, Fuel Surcharge, Auto-calculated COGS |
| **SKU Categorisation** | SKU Category, SKU Subcategory (for internal reporting) |
| **Product Specifications** | Repeater: Name / Value / Unit pairs (e.g. Dimensions: 10×5×3 cm) |
| **Shipping Profile** | Assign a brand-level shipping profile |

#### How a shipping rate is chosen

A shipping profile (**Products → Shipping Profiles**) holds two separate rates - **Mainland US Cost** and **International Cost (outside Mainland US)** - plus an optional list of per-country overrides. At checkout the buyer's country selects exactly one of them:

| Buyer's country | Rate applied |
| - | - |
| Matches a per-country override | That override's cost |
| `US` | **Mainland US Cost** |
| Anything else | **International Cost** |

<Warning>
  **The two rates are independent - neither one falls back to the other.** Leaving a field empty does not mean "charge the other rate". It means **free shipping for that region**, applied silently with no warning.

  A profile set to Mainland US `$10` with International left blank charges $10 in the US and **$0.00 in every other country\*\*. The checkout's Shipping line renders `$0.00` and the order is placed with no shipping charge at all.

  This is easiest to hit while previewing your own checkout from outside the US: the country field defaults to the visitor's geolocated country, so the page shows `$0.00` shipping and looks broken even though the US rate is configured correctly. Switch the country to **United States** to see the US rate apply.

  Fill in **both** fields on every profile. If you truly do not ship outside the US, restrict which countries the checkout will accept via `checkout_settings.countries` (see [Countries and US states allowlist](/checkouts/checkout-functionality-reference)) instead of leaving International blank.
</Warning>

<Note>
  **"Mainland US" means country = `US`.** Alaska, Hawaii and US territories are not separated out - they receive the Mainland US rate. To charge them differently, add a per-country override or a state-specific rate.
</Note>

A product with **no** shipping profile assigned also ships free. Assign a profile to every physical product - **including upsell and downsell products**, which are charged as separate orders - or use the Products list's bulk **Set shipping profile** action to apply one to many products at once.

***

### Merchants Tab

Configure product identifiers per payment gateway integration.

For each active payment gateway (NMI, Stripe, BuyGoods, ClickBank, etc.) enter the product ID used on that gateway. These are exposed as `product | merchantPriceId:'stripe'` in templates.

***

### Bonuses Tab

Assign bonus products that customers receive when purchasing this product. Select from products with `classification = bonus`.

***

### Files Tab

Visible when product type is **Digital** or classification is **Bonus**.

Add one or more downloadable files:

* **Purpose** — Digital or Bonus
* **Title** — File display name
* **Description** — Optional description
* **Image** — Thumbnail image
* **File** — Upload or URL
* **Primary** — Mark as primary file for this purpose

***

### Courses Tab

Assign courses that customers are automatically enrolled in after purchase.

***

### Attributes Tab

Fill in values for brand-level Product Attributes defined under **Settings → Products → Product Attributes**.

Supports all field types: text, textarea, rich text, number, boolean, date, select, multiselect, color, image URL, file URL, and JSON.

Attributes with `applies_to = variant` are managed per variant in the Variants tab, not here.

***

### Custom Attributes Tab

Legacy unstructured key/value pairs for ad-hoc product metadata (e.g. a download URL or custom flag).

> **Note:** For structured, typed attributes, use the Attributes tab with Product Attribute definitions instead. Custom Attributes are a legacy system.

***

### Variants Tab

Define product variants (e.g. Color, Size) with individual pricing.

1. **Select variant options** — Check which brand-level variant options apply to this product (managed under Settings → Variant Options)
2. **Add variants** — Each row shows one field per selected option plus Code and Price

***

## Template Reference

All product data is available in ElasticFunnels templates via data functions and filters. Functions are called with `{% set x = FunctionName(args) %}` or inline. Filters are applied with `{{ value | filterName:arg }}`.

***

### Product Object Shape

Every product returned by a data function has the following fields:

| Field | Type | Description |
| - | - | - |
| `id` | `number` | Unique product ID |
| `brand_id` | `number` | Brand this product belongs to |
| `title` | `string` | Display title — uses `checkout_title` when set, otherwise `title` |
| `checkout_title` | `string \| null` | Raw checkout title (before effective resolution) |
| `code` | `string` | Unique product code used in buy links |
| `type` | `"physical" \| "digital" \| "service"` | Product type |
| `classification` | `"main" \| "upsell" \| "downsell" \| "bump" \| "bonus"` | Role in the funnel |
| `status` | `"active" \| "draft" \| "archived"` | Visibility status |
| `show_in_frontend` | `boolean` | `true` when the product is listed in shop and catalog pages. Does not affect whether it can be sold |
| `price` | `number` | Selling price |
| `retail_price` | `number \| null` | Compare-at (strikethrough) price |
| `currency` | `string \| null` | 3-letter currency code (e.g. `"USD"`); `null` = brand default |
| `sku` | `string \| null` | Stock-keeping unit |
| `barcode` | `string \| null` | UPC / EAN barcode |
| `units` | `number \| null` | Package quantity |
| `physical_units_per_product` | `number \| null` | Individual units inside one package (for per-unit pricing) |
| `description` | `string \| null` | Full product description (HTML) |
| `short_description` | `string \| null` | Brief summary |
| `image` | `string \| null` | Primary image CDN URL |
| `gallery` | `string[]` | Additional image CDN URLs — **always an array**, never `null` |
| `has_gallery` | `boolean` | `true` when `gallery.length > 0` |
| `has_description` | `boolean` | `true` when `description` is non-empty |
| `in_stock` | `boolean` | `true` when `inventory_quantity` is `null` or `> 0` |
| `inventory_quantity` | `number \| null` | Current stock count; `null` = unlimited |
| `inventory_policy` | `"continue" \| "deny"` | Behaviour when out of stock |
| `is_subscription` | `boolean` | Whether recurring billing is enabled |
| `subscription_frequency` | `number \| null` | Billing interval value (e.g. `1`) |
| `subscription_frequency_unit` | `"day" \| "week" \| "month" \| "year" \| null` | Billing interval unit |
| `subscription_trial_days` | `number \| null` | Free trial days before first charge |
| `subscription_first_charge_free` | `boolean` | First order ships free (customer pays shipping only) |
| `is_build_a_box` | `boolean` | Build-a-Box subscription mode |
| `seo_title` | `string \| null` | SEO page title |
| `seo_slug` | `string \| null` | URL slug for storefront product pages |
| `seo_description` | `string \| null` | Meta description |
| `product_category_id` | `number \| null` | Assigned category ID |
| `product_subcategory_id` | `number \| null` | Assigned subcategory ID |
| `category_name` | `string \| null` | Category display name (denormalised) |
| `subcategory_name` | `string \| null` | Subcategory display name (denormalised) |
| `product_files` | `ProductFile[]` | All attached files |
| `digital_files` | `ProductFile[]` | Subset: digital download files |
| `bonus_files` | `ProductFile[]` | Subset: bonus files |
| `primary_download_url` | `string \| null` | URL of the primary digital file |
| `merchant_product_ids` | `Record<string, string>` | Gateway → merchant product ID map (e.g. `{ stripe: "price_xxx" }`) |

#### ProductFile shape

Each item in `product_files`, `digital_files`, and `bonus_files`:

| Field | Type | Description |
| - | - | - |
| `url` | `string` | CDN URL of the file |
| `title` | `string \| null` | File display name |
| `description` | `string \| null` | File description |
| `image` | `string \| null` | Thumbnail image URL |
| `purpose` | `"digital" \| "bonus"` | Whether this is a digital or bonus file |
| `kind` | `"audio" \| "video" \| "document" \| "image" \| "archive" \| "file"` | Inferred from MIME type |
| `mime_type` | `string \| null` | MIME type |
| `size` | `number \| null` | File size in bytes |
| `extension` | `string \| null` | File extension (e.g. `"pdf"`) |
| `is_primary` | `boolean` | Whether this is the primary file for its purpose |
| `sort_order` | `number` | Display order |

***

### Data Functions

#### `getProduct(code)`

Loads a single product by its **code** for the current brand. Also pre-loads structured attribute values so the `attr` and `attrLabel` filters work immediately on the returned object.

```
{% set product = getProduct('PROD-001') %}
{{ product.title }} — {{ product.price | formatPrice:product.currency }}
```

**Returns:** `ProductObject | null`

***

#### `getProducts(filters?)`

Returns the brand's products, with optional filters. Products with **Show in frontend** off are left out unless you ask for them, see [Storefront visibility](/backend-template-engine/products-and-shipping#storefront-visibility).

| Filter key | Type | Description |
| - | - | - |
| `type` | `string` | `"physical"`, `"digital"`, or `"service"` |
| `classification` | `string` | `"main"`, `"upsell"`, `"downsell"`, `"bump"`, or `"bonus"` |
| `codes` | `string` | Comma-separated list of product codes |
| `category_id` | `number \| string` | Filter by product category ID |
| `subcategory_id` | `number \| string` | Filter by subcategory ID |
| `show_in_frontend` | `boolean \| string` | Defaults to `true`. Pass `'any'` for everything, `false` for hidden products only |

```
{% set upsells = getProducts({ classification: 'upsell' }) %}
{% for p in upsells %}
  <div>{{ p.title }} — {{ p.price | formatPrice:p.currency }}</div>
{% endfor %}
```

**Returns:** `ProductObject[]`

***

#### `getAllProducts()`

Returns every product for the brand without filters. Fastest when you need to iterate all products and filter in the template.

```
{% set all = getAllProducts() %}
{% for p in all %}{% if p.status == 'active' %}
  {{ p.title }}
{% endif %}{% endfor %}
```

**Returns:** `ProductObject[]`

***

#### `getProductCategories(filters?)`

Returns product categories. By default returns a full tree ordered by position, then name, with a `depth` field.

| Filter key | Type | Description |
| - | - | - |
| `top_level` | `boolean` | Only root categories (no parent) |
| `parent_id` | `number \| string` | Only direct children of this category |
| `flat` | `boolean` | Return flat list instead of tree |
| `tree` | `boolean` | Set `false` to force flat list |

Each item: `{ id, name, position, parent_id, depth? }`

```
{% set cats = getProductCategories({ top_level: true }) %}
{% for cat in cats %}
  <h3>{{ cat.name }}</h3>
  {% set subs = getProductCategories({ parent_id: cat.id }) %}
  {% for sub in subs %}<span>{{ sub.name }}</span>{% endfor %}
{% endfor %}
```

**Returns:** `CategoryObject[]`

***

#### `productDownloads(product)`

Flattens all downloadable files attached to a product into a single deduplicated array. Useful for rendering download lists on digital product pages.

```
{% set files = productDownloads(product) %}
{% for f in files %}
  <a href="{{ f.url }}">{{ f.title or f.extension | upper }} — {{ f.kind }}</a>
{% endfor %}
```

Each item: `{ url, title, kind, purpose, extension, mime_type, size, is_primary, sort_order }`

**Returns:** `DownloadObject[]`

***

#### `productSavings(product)`

Returns a structured savings breakdown comparing `retail_price` to `price`. Returns `null` if there is no saving.

```
{% set savings = productSavings(product) %}
{% if savings and savings.amount > 0 %}
  You save {{ savings.amountFormatted }} ({{ savings.percent }}% off)
{% endif %}
```

**Returns:** `{ amount: number, percent: number, amountFormatted: string, percentFormatted: string } | null`

***

#### `subscriptionSummary(product)`

Generates a human-readable billing summary string for a subscription product (e.g. `"7-day free trial · Every 1 month"`).

```
{% if product.is_subscription %}
  <p>{{ subscriptionSummary(product) }}</p>
{% endif %}
```

**Returns:** `string`

***

#### `getProductAttributes(filters?)`

Returns the brand's structured attribute definitions. See [Product Attributes](/products/product-attributes) for details on attribute types and scoping.

| Filter key | Type | Description |
| - | - | - |
| `visible` | `boolean` | Only attributes with `visible_on_product_page = true` |
| `filterable` | `boolean` | Only attributes marked as filterable |
| `applies_to` | `"product" \| "variant"` | Filter by scope |

Each item: `{ id, name, slug, type, applies_to, options, filterable, visible_on_product_page, required }`

**Returns:** `AttributeDefinition[]`

***

#### `getProductAttributeValues(product)`

Returns all attribute values for a product as a `{ slug: value }` map.

```
{% set defs = getProductAttributes({ visible: true }) %}
{% set vals = getProductAttributeValues(product) %}
{% for attr in defs %}
  <dt>{{ attr.name }}</dt>
  <dd>{{ vals[attr.slug] }}</dd>
{% endfor %}
```

**Returns:** `Record<string, string | number | boolean>`

***

### Filters

#### `formatPrice`

Formats a numeric price using the brand's active currency locale.

```
{{ product.price | formatPrice:product.currency }}
{# → "$49.00" #}

{{ 9.99 | formatPrice:'EUR' }}
{# → "€9.99" #}
```

***

#### `savings`

Computes the saving between `retail_price` and `price` and returns a formatted string.

| Format | Example output |
| - | - |
| *(default)* | `"Save $20"` |
| `'percent'` | `"Save 25%"` |
| `'both'` | `"Save $20 (25% off)"` |

```
{{ product | savings }}
{{ product | savings:'percent' }}
{{ product | savings:'both' }}
```

Returns `""` when `retail_price` is not set or not greater than `price`.

***

#### `compareAt`

Formats `retail_price` as a "Was \$X" string.

```
{{ product | compareAt }}
{# → "Was $99.00" #}
```

Returns `""` when `retail_price` is not set.

***

#### `pricePerUnit`

Divides `price` by `physical_units_per_product` to give the per-unit price. Useful for "per bottle" or "per capsule" displays.

```
{{ product | pricePerUnit }}
{# → "33.00" (for a 6-pack at $198) #}
```

**Returns:** `string` (float formatted to 2 decimal places)

***

#### `subscriptionLabel`

Short-form billing label. Returns trial info if present, otherwise the billing frequency.

```
{{ product | subscriptionLabel }}
{# → "7-day free trial"  or  "Every 1 month" #}
```

Returns `""` for non-subscription products.

***

#### `merchantPriceId`

Looks up the merchant-specific product identifier from `merchant_product_ids` (configured in the Merchants tab).

```
{{ product | merchantPriceId:'stripe' }}
{# → "price_1abc..." #}

{{ product | merchantPriceId:'nmi' }}
```

***

#### `attr`

Returns the value of a structured attribute by its slug. Only works on products loaded via `getProduct` (which pre-loads attribute values).

```
{% set product = getProduct('MY-PRODUCT') %}
{{ product | attr:'material' }}
{# → "Organic Cotton" #}
```

Returns `""` when the attribute is not set.

***

#### `attrLabel`

Returns the human-readable **label** (name) of a structured attribute definition by slug.

```
{{ product | attrLabel:'material' }}
{# → "Material" #}
```

***

### Gallery

`product.gallery` is a `string[]` — an array of CDN image URLs. It is always an array (never `null` or a JSON string). `product.has_gallery` is `true` when the array has at least one entry.

```html theme={null}
{% if product.has_gallery %}
<div class="product-gallery">
  {% for url in product.gallery %}
  <img src="{{ url }}" alt="{{ product.title }}" />
  {% endfor %}
</div>
{% endif %}
```

Show the primary image with gallery fallback:

```html theme={null}
{% set mainImage = product.image or (product.gallery[0] if product.has_gallery) %}
{% if mainImage %}
<img src="{{ mainImage }}" alt="{{ product.title }}" />
{% endif %}
```


# Subscription Upsells
Source: https://docs.elasticfunnels.io/products/subscription-upsells

Upgrade, downgrade, or cancel existing subscriptions mid-funnel and transition customers to new offers without a second checkout

Subscription upsells let you modify an existing subscription **inside your funnel flow** — upgrade it, cancel it, or swap it for a different offer — all without sending the customer through another checkout page. This is different from a standard [one-click upsell](/products/upsells), which charges the customer for an additional product. A subscription upsell changes the product the customer is *already* paying for.

## How It Works

A typical subscription upsell flow looks like this:

1. **Customer purchases a recurring product** (e.g. monthly supplement subscription)
2. **Upsell page offers an upgrade** — "Switch to the 6-bottle plan and save 40%"
3. **Customer accepts** → The existing subscription is changed to the new SKU via API. No new charge, no checkout redirect.
4. **Next page offers a lifetime deal** — "Cancel your subscription and get lifetime access for a one-time payment"
5. **Customer accepts** → Subscription is cancelled via API, then a standard `[UPSELL=lifetime_product]` one-click purchase processes the new charge.

The key difference from a traditional upsell: **steps 3 and 5 modify the existing subscription first**, then optionally navigate to a purchase step. The modification is an API call (1–3 seconds), not a checkout redirect.

```
Standard Upsell:       [UPSELL=product] → one-click charge → next page
Subscription Upsell:   ef.sub.upgrade()  → API modifies subscription → then navigate
```

## Tags

Two new bracket tags handle subscription modifications. They work with any supported gateway (ClickBank, NMI).

### Upgrade Subscription

```
[UPSELL_UPGRADE=old_sku, new_sku]
```

Generates a JavaScript call that upgrades the customer's subscription from `old_sku` to `new_sku`. Use this in a link `href` — when clicked, it calls the server API to change the subscription product.

* **old\_sku** — The product code the customer is currently subscribed to
* **new\_sku** — The product code to switch them to

Spaces around the comma are allowed: `[UPSELL_UPGRADE=15, 16]` and `[UPSELL_UPGRADE=15,16]` both work.

### Cancel Subscription

```
[UPSELL_CANCEL]
```

Generates a JavaScript call that cancels the customer's current subscription. Typically used before offering a lifetime/one-time purchase as an alternative.

### Usage in Links

```html theme={null}
<!-- Upgrade button -->
<a href="[UPSELL_UPGRADE=monthly_basic, monthly_premium]">
  Upgrade to Premium
</a>

<!-- Cancel button (usually paired with a lifetime offer on the next screen) -->
<a href="[UPSELL_CANCEL]">
  Switch to Lifetime Access
</a>

<!-- Standard decline — skip this offer entirely -->
<a href="[UPSELL_DECLINE]">
  No thanks
</a>
```

<Note>
  These tags do **not** redirect to a checkout page like `[BUY=]` or `[UPSELL=]`. They execute an API call in the background to modify the existing subscription. If you need to charge for a new product after cancelling, combine `[UPSELL_CANCEL]` with a subsequent `[UPSELL=lifetime_product]` step.
</Note>

## Template Functions

If you use the Backend Template Engine, you can generate subscription action URLs with template functions instead of bracket tags:

```html theme={null}
<a href="{{ upsell_upgrade('monthly_basic', 'monthly_premium') }}">
  Upgrade to Premium
</a>

<a href="{{ upsell_cancel() }}">
  Cancel Subscription
</a>
```

These produce the same output as the bracket tags. You can also use them as filters:

```html theme={null}
<a href="{{ 'monthly_basic' | upsell_upgrade('monthly_premium') }}">
  Upgrade to Premium
</a>
```

## JavaScript API (`ef.sub`)

For full control, use the `ef.sub` namespace on `window.ef`. This is available on any page where the merchant supports subscriptions (ClickBank or NMI). The script is loaded automatically.

### ef.sub.upgrade(oldSku, newSku)

Calls the server API to upgrade the subscription. Returns a Promise that resolves on success or rejects on error. No UI is shown — use this when you want to handle the result yourself.

```javascript theme={null}
ef.sub.upgrade('15', '16').then(function() {
  // subscription upgraded
}).catch(function(err) {
  alert('Upgrade failed: ' + err.message);
});
```

### ef.sub.cancel()

Calls the server API to cancel the subscription. Returns a Promise.

```javascript theme={null}
ef.sub.cancel().then(function() {
  // subscription cancelled
}).catch(function(err) {
  alert('Cancel failed: ' + err.message);
});
```

### ef.sub.upgradeThenNavigate(oldSku, newSku, url)

Upgrades the subscription, shows a loading overlay while the API call is in progress, then navigates to `url` on success. On error, the overlay is dismissed and an error message is shown.

```javascript theme={null}
ef.sub.upgradeThenNavigate('15', '16', '/b?product=premium_annual');
```

### ef.sub.cancelThenNavigate(url)

Cancels the subscription, shows a loading overlay, then navigates to `url` on success.

```javascript theme={null}
ef.sub.cancelThenNavigate('/b?product=lifetime_access');
```

<Tip>
  The `*ThenNavigate` methods include a built-in loading overlay with a spinner and status message ("Upgrading your subscription..." / "Processing..."). You don't need to build your own loading UI. The raw methods (`upgrade`, `cancel`) have no UI for cases where you want full control.
</Tip>

## Subscription Containers

Three page builder containers let you show different content based on the result of a subscription API call. Drag them from the **Offer** category in the block palette.

| Container | Default state | Shown when |
| - | - | - |
| **Sub Pending** | Visible | Hidden when any `ef.sub.*` call completes |
| **Sub Success** | Hidden | Shown when the API call succeeds |
| **Sub Error** | Hidden | Shown when the API call fails |

These containers auto-toggle when `ef.sub.upgrade()` or `ef.sub.cancel()` completes. If they're not on the page, the toggle is a no-op — you can always handle state manually with your own JavaScript.

### Multi-Screen Example

A common pattern is to show the upgrade offer first, then reveal the lifetime offer after the upgrade succeeds:

```html theme={null}
<sub-pending>
  <h2>Upgrade to the 6-Bottle Plan and Save 40%</h2>
  <p>Your current monthly subscription will be switched immediately.</p>
  <a href="javascript:void(0)" onclick="ef.sub.upgrade('15','16')">
    Yes, Upgrade My Plan
  </a>
  <a href="[UPSELL_DECLINE]">No thanks, keep my current plan</a>
</sub-pending>

<sub-success>
  <h2>You're upgraded! Now unlock lifetime access.</h2>
  <p>Cancel your subscription and get lifetime access for one payment of $197.</p>
  <a href="javascript:void(0)"
     onclick="ef.sub.cancelThenNavigate('[UPSELL=lifetime_access]')">
    Get Lifetime Access
  </a>
  <a href="[UPSELL_DECLINE]">No thanks, keep my upgraded subscription</a>
</sub-success>

<sub-error>
  <p>Something went wrong. Please try again.</p>
  <a href="javascript:void(0)" onclick="ef.sub.upgrade('15','16')">
    Retry Upgrade
  </a>
</sub-error>
```

**Flow:**

```
Page loads → <sub-pending> visible (upgrade offer)
   ↓ customer clicks "Yes, Upgrade"
ef.sub.upgrade('15','16') fires → loading overlay → API call
   ↓ success
<sub-pending> hides, <sub-success> shows (lifetime offer)
   ↓ customer clicks "Get Lifetime Access"
ef.sub.cancelThenNavigate() → cancels subscription → navigates to [UPSELL=lifetime_access]
   ↓
Standard one-click upsell processes the lifetime purchase
```

<Note>
  You can also build this flow entirely without containers — use the `ef.sub.*` API with your own JavaScript to show/hide elements, or use the `*ThenNavigate` methods to handle the full sequence in one click.
</Note>

## Session Variables

After a subscription modification succeeds, session variables are set so the **next page load** (e.g. thank-you page) can display relevant information:

| Variable | Type | Description |
| - | - | - |
| `session.subscription_upgraded` | boolean | `true` if an upgrade happened during this session |
| `session.subscription_cancelled` | boolean | `true` if a cancellation happened during this session |
| `session.subscription_old_sku` | string | The product code before the change |
| `session.subscription_new_sku` | string | The new product code (upgrade only) |

Use these in Backend Template Engine directives on your thank-you page:

```html theme={null}
@if(session.subscription_upgraded)
  <p>Your subscription has been upgraded to {{ session.subscription_new_sku }}.</p>
@endif

@if(session.subscription_cancelled)
  <p>Your previous subscription has been cancelled.</p>
@endif
```

The order display (`<order>` tags and `getOrders()` template data) also reflects the updated product after a subscription change — the session order data is updated when the API call succeeds.

## ClickBank Configuration

ClickBank subscription modifications use the ClickBank REST API (Orders API for upgrades, Tickets API for cancellations). This requires a **Developer API Key** in addition to the standard merchant setup.

### Step 1: Get Your ClickBank Developer API Key

1. Log into your ClickBank account
2. Go to **Settings** → **API Keys** (or **Account Settings** → **Developer Keys**)
3. Create or copy your **Developer API Key** (also called Clerk API Key)

<Warning>
  The Developer API Key is different from the Encryption Key you already configured. The encryption key secures postback data; the Developer API Key authenticates REST API calls for subscription management.
</Warning>

### Step 2: Add the API Key to Your Merchant

1. In ElasticFunnels, go to **Settings** → **Merchants**
2. Edit your ClickBank merchant
3. Enter the **ClickBank API Key (Developer/Clerk Key)** in the credentials section
4. Save

### Step 3: Configure Your Products

Ensure both the old and new subscription products exist in your ClickBank pitch flow and in your ElasticFunnels product list. The product codes used in `[UPSELL_UPGRADE=old, new]` must match the ClickBank item numbers exactly.

### How It Works with ClickBank

* **Upgrade** (`ef.sub.upgrade`): Calls the ClickBank Orders API `changeProduct` endpoint to switch the customer's recurring billing from one item to another. The customer's billing cycle and payment method stay the same.
* **Cancel** (`ef.sub.cancel`): Creates a cancellation ticket via the ClickBank Tickets API. The subscription stops at the end of the current billing period.
* **Receipt resolution**: The system automatically uses the customer's ClickBank receipt from the active session — you don't need to pass it manually.

### ClickBank Postback Events

After a subscription change, ClickBank sends Instant Notification Service (INS) events that ElasticFunnels processes automatically:

| ClickBank Event | What Happens |
| - | - |
| `SUBSCRIPTION-CHG` | Conversion updated with new product code |
| `CANCEL-REBILL` | Conversion marked as subscription cancelled |
| `UNCANCEL-REBILL` | Conversion updated — subscription reactivated |

## NMI Configuration

For NMI merchants, subscription management is handled internally by ElasticFunnels — no additional API keys are needed beyond the standard NMI merchant setup.

* **Upgrade**: Updates the subscription in ElasticFunnels so the next billing cycle uses the new product's price and terms.
* **Cancel**: Cancels the subscription in ElasticFunnels so no further billing cycles are processed.

## Complete Flow Example

Here's a full subscription upsell funnel for a supplement business:

```
Main Sales Page
  └── [BUY=monthly_3_bottles] → Customer purchases 3-bottle monthly subscription
        ↓ On Purchase
Subscription Upsell Page
  ├── <sub-pending>: "Upgrade to 6-bottle plan, save 40%"
  │     ├── ef.sub.upgrade('monthly_3_bottles', 'monthly_6_bottles') → Accept
  │     └── [UPSELL_DECLINE] → Decline
  │
  ├── <sub-success>: "Now get lifetime access for $197"
  │     ├── ef.sub.cancelThenNavigate('[UPSELL=lifetime_access]') → Accept lifetime
  │     └── [UPSELL_DECLINE] → Keep upgraded subscription
  │
  └── <sub-error>: "Something went wrong" + Retry button
        ↓
Thank You Page
  └── Shows order with updated product info via session variables
```

**Three possible outcomes:**

1. **Upgrade + Lifetime**: Customer upgrades subscription, then cancels it for lifetime access (best outcome)
2. **Upgrade only**: Customer upgrades subscription but declines lifetime (good outcome)
3. **Decline all**: Customer keeps original subscription unchanged

## Troubleshooting

### Upgrade/Cancel Not Working

* Verify the product codes match exactly (case-sensitive)
* For ClickBank: ensure the Developer API Key is configured in merchant settings
* Check that the customer has an active purchase session (subscription upsells require a prior purchase)
* Open the browser console — `ef.sub.*` methods log errors to the console

### Containers Not Toggling

* Ensure the subscription script is loaded (check for `ef-subscription.js` in page source)
* The script only loads for ClickBank and NMI merchants — other gateways don't support subscription modification
* Verify containers are using the correct custom tags: `<sub-pending>`, `<sub-success>`, `<sub-error>`

### Order Display Not Updating

* Session variables are set after the API call succeeds — they're available on the **next page load**, not the current page
* If the order still shows the old product, the customer may have navigated directly to the thank-you page without going through the subscription modification step
* ClickBank postback events update the conversion in the database asynchronously — there may be a short delay

### ClickBank API Errors

* **401 Unauthorized**: Developer API Key is missing or incorrect
* **403 Forbidden**: API key doesn't have permission for the requested operation
* **404 Not Found**: Receipt or transaction not found — verify the customer has an active subscription
* **409 Conflict**: Product change not allowed — check that both SKUs are valid in the pitch flow

## Related Documentation

* [Upsells](/products/upsells) — Standard one-click upsell setup
* [Buy Links](/products/buy-links) — Purchase button configuration
* [Advanced Purchase Links](/products/advanced-purchase-links) — Dropdown product insertion
* [ClickBank Merchant](/merchants/clickbank) — ClickBank pitch flow and postback setup
* [EF API (window.ef)](/funnels/window-api) — Client-side JavaScript API reference
* [Containers](/pages/containers) — All container types and patterns
* [Variables and Filters](/backend-template-engine/variables-and-filters) — Backend template engine reference


# Upsells
Source: https://docs.elasticfunnels.io/products/upsells

Set up upsell and downsell pages with one-click purchasing to maximize revenue per customer

Upsells allow you to present additional offers after a customer makes their initial purchase. ElasticFunnels supports one-click upsells that process payments instantly without redirecting customers to a checkout page.

## How Upsells Work

After a customer completes their initial purchase, they're redirected through your funnel flow. Upsell pages present additional offers that customers can accept or decline:

1. **Customer purchases main product** → Redirected to upsell page
2. **Upsell page displays** → Customer sees additional offer
3. **Customer accepts or declines** → Flow continues to next step or thank you page

### One-Click Upsells vs Checkout Redirect

The tag you use determines the customer experience:

| Tag | Behavior | When to Use |
| - | - | - |
| `[UPSELL=]` or `[DOWNSELL=]` | **One-click purchase** - No checkout page, payment processed instantly | Post-purchase upsell pages (customer already has an active purchase session) |
| `[BUY=]` | **Redirect to checkout** - Customer goes to merchant checkout page | Main sales pages, or when there's no active purchase session |

<Note>
  **Important:** One-click upsells require an active purchase session. If the customer doesn't have an active session (e.g., they navigated directly to an upsell page), clicking an `[UPSELL=]` link will redirect them to the checkout page instead.
</Note>

## Setting Up Upsell Pages

### Step 1: Create Your Upsell Page

1. Go to **Pages** → **Create New Page**
2. Design your upsell offer page with:
   * Clear value proposition
   * Product benefits
   * Accept button (upsell link)
   * Decline button (decline link)

### Step 2: Add Upsell Links

Use these tags in your page links:

#### Accept Upsell Button

```
[UPSELL=your_product_code]
```

#### Decline Button

```
[UPSELL_DECLINE]
```

You can also specify a product for the decline (useful for downsells):

```
[UPSELL_DECLINE=downsell_product_code]
```

### Step 3: Configure Funnel Flow

Each page node in the funnel builder has built-in **On Purchase** and **On Decline** connection points.

1. Open your funnel in the builder
2. Add a **Page node** for your upsell page
3. The page node automatically shows **On Purchase** and **On Decline** connections
4. Connect **On Purchase** to the next step (another page, redirect, split test, etc.)
5. Connect **On Decline** to a downsell page or thank you page

**Example Flow:**

```
Upsell Page (6 Bottles)
    ├── On Purchase → Thank You Page
    └── On Decline → Downsell Page (3 Bottles)
                         ├── On Purchase → Thank You Page
                         └── On Decline → Thank You Page
```

### Available Nodes After Purchase/Decline

After the On Purchase or On Decline connection, you can add:

* **Go to Page** - Navigate to another page in your funnel
* **Redirect to URL** - Redirect to an external URL
* **Split Test** - A/B test different paths
* **Product Check** - Check which product was purchased
* **Script Rule** - Apply conditional logic
* **Tag User** - Add tags to the customer
* **Whitelist visitor** - Mark visitor as whitelisted
* **Is Whitelisted?** - Check if visitor is whitelisted
* **Has Tag** - Check if user has a specific tag
* **Is Test Order?** - Check if this is a test transaction

## Upsell Link Tags

### Basic Upsell

```
[UPSELL=product_code]
```

Processes the upsell purchase and continues the funnel flow.

### Downsell

```
[DOWNSELL=product_code]
```

Works the same as `[UPSELL]` but allows you to semantically differentiate downsell offers in your tracking and analytics.

### Decline Link

```
[UPSELL_DECLINE]
```

Skips the current upsell and proceeds to the next funnel step (either another upsell or the thank you page).

### Decline with Downsell Tracking

```
[UPSELL_DECLINE=product_code]
```

Declines the current offer but tracks which product was declined for analytics.

### With Extra Parameters

```
[UPSELL=product_code extra=campaign_data]
```

## Funnel Node Configuration

### Using Copy Node URL

For ClickBank, Buygoods, and Digistore24, you need to configure redirect URLs in the merchant's platform (pitch flow settings).

Each **On Purchase** and **On Decline** node has a **Copy Node URL** button:

1. In your funnel builder, locate the **On Purchase** or **On Decline** node
2. Click the **Copy Node URL** button
3. Paste this URL into your merchant's pitch flow or redirect settings

This decouples your funnel from specific page URLs, allowing you to:

* Split test different upsell pages without changing merchant settings
* Swap pages without re-approval from the merchant
* Maintain consistent tracking across page changes

<Warning>
  Always use Copy Node URL when configuring your merchant's pitch flow. Direct page URLs will break if you rename or replace pages.
</Warning>

## How One-Click Upsells Work

When a customer has an active purchase session:

1. **Customer clicks `[UPSELL=]` button** → Payment processed by the merchant (ClickBank, Buygoods, or Digistore24)
2. **No checkout page shown** → Customer stays in the funnel flow
3. **Automatic redirect** → Customer proceeds to the next funnel step

### Session Requirements

For one-click upsells to work:

* Customer must have completed a purchase in the current session
* The purchase session must still be active
* The upsell must be part of the same funnel flow

<Note>
  Use **Copy Node URL** in your funnel builder to get the correct redirect URLs for configuring your merchant's pitch flow settings.
</Note>

## Types of Upsells

### One-Click Upsell

* Post-purchase offer using `[UPSELL=product_code]` tag
* Customer can purchase with one click
* No checkout page - payment processed instantly
* Requires active purchase session

### Downsell

* Lower-priced alternative shown when upsell is declined
* Uses `[DOWNSELL=product_code]` tag
* Helps recover potential lost sales
* Often a scaled-down version of the upsell
* Can be chained: Upsell → Decline → Downsell → Decline → Thank You

## Upsell Page Best Practices

### Essential Elements

* **Clear value proposition**: Why they need this additional product
* **Urgency**: Limited time or quantity offers
* **Social proof**: Testimonials specific to the upsell
* **Simple checkout**: One clear "Yes" button, one clear "No Thanks" button

### Content Strategy

* **Complement the main purchase**: Related but distinct value
* **Address remaining pain points**: Solve additional problems
* **Show before/after scenarios**: Demonstrate the enhanced outcome
* **Use purchase confirmation**: "Since you just purchased X, you qualify for Y"

### Button Placement

```html theme={null}
<!-- Accept button - make it prominent -->
<a href="[UPSELL=premium_package]" class="btn-accept">
  Yes! Add This To My Order
</a>

<!-- Decline button - clear but less prominent -->
<a href="[UPSELL_DECLINE]" class="btn-decline">
  No thanks, I'll pass on this offer
</a>
```

## Advanced Upsell Strategies

### Sequential Upsells

Chain multiple upsell offers:

```
Main Sale → Upsell 1 ($97) → Upsell 2 ($47) → Downsell ($27) → Thank You
```

### Conditional Upsells

Use Page Events to show different upsells based on:

* Original purchase amount
* Customer location
* Traffic source
* Previous purchase history

### Tracking Accepted Upsells

Use the `accepted_upsells` variable in Script Rules to customize content based on whether the customer has accepted any upsells:

```javascript theme={null}
// In a Script Rule condition
customer.accepted_upsells === true
```

## Measuring Upsell Performance

### Key Metrics

* **Upsell take rate**: Percentage who accept each upsell
* **Average order value (AOV)**: Total revenue including upsells
* **Revenue per visitor (RPV)**: Lifetime value impact
* **Decline rate**: How many skip each offer

### Optimization Tips

* A/B test different upsell offers and pricing
* Test upsell page designs and copy
* Experiment with the number of upsells in a sequence
* Monitor customer satisfaction (too many upsells can harm brand)

## Troubleshooting

### Common Issues

**Upsell link not working:**

* Verify the product code matches exactly
* Check that the product exists in your Products list
* Ensure the product has the correct merchant mapping

**One-click not processing:**

* Verify you're using `[UPSELL=]` or `[DOWNSELL=]` tags (not `[BUY=]`)
* Check that session data is preserved (cookies enabled)
* Ensure the main sale completed successfully
* Customer must have an active purchase session

**Redirect failing after purchase/decline:**

* Verify Copy Node URL was used correctly in merchant pitch flow
* Check merchant pitch flow configuration
* Ensure redirect URLs are properly URL-encoded

**Wrong page showing after purchase/decline:**

* Check funnel node connections
* Verify Purchase and Decline nodes point to correct pages
* Test the full flow from main sale to thank you page

### Testing Your Upsells

1. Complete a test purchase through the main sale
2. Verify upsell page loads correctly
3. Test both accept and decline paths
4. Confirm correct pages display at each step
5. Verify payments process correctly (use test mode)

<Note>
  For ClickBank, Buygoods, and Digistore24, use the platform's test mode or sandbox environment to verify the complete flow without processing real payments.
</Note>

## Related Documentation

* [QuickBuy (Card on File)](/products/quickbuy) - Charge returning customers with their stored card outside a funnel
* [Subscription Upsells](/products/subscription-upsells) - Upgrade or cancel existing subscriptions mid-funnel
* [Buy Links](/products/buy-links) - Setting up purchase buttons
* [Checkout Redirect Behavior](/funnels/checkout-redirect-behavior) - Understanding redirect flows
* [Create Funnel](/funnels/create-funnel) - Building your funnel structure
* [ClickBank Merchant](/merchants/clickbank) - ClickBank pitch flow setup
* [Buygoods Merchant](/merchants/buygoods) - Buygoods configuration
* [Digistore24 Merchant](/merchants/digistore24) - Digistore24 setup


# Product Variants
Source: https://docs.elasticfunnels.io/products/variants

Manage product variants: define variant axes (Color, Size), configure option values, set per-variant pricing, and assign variant attributes

Product variants let you sell multiple versions of a product (e.g., different sizes or colors) under a single product record, each with its own price and code.

***

## How Variants Work

Variants are built from **Variant Options** — brand-level axis definitions (e.g., "Color", "Size"). On the product, you select which options apply, then define each combination as an individual variant row.

***

## Linking a Variant to an Existing Product

A variant normally **points at a product you already have** rather than owning its own
commercial data. Set **Linked product** on the variant row and everything downstream —
SKU, inventory, fulfilment, payouts, `merchant_product_ids`, postback matching — keeps
resolving through that product's code, exactly as it did before.

This is the difference from Shopify, and it is deliberate. In ElasticFunnels the product
code is the identity the whole system is keyed on, so a variant that owned a separate
price and SKU would need all of that duplicated. Linking keeps one source of truth:

* **The variant** is presentation — which option values it represents, what order it
  appears in, which one is selected by default.
* **The linked product** stays the sellable thing, unchanged.

### Worked example: pack sizes

A supplement sold as 1, 3 and 6-bottle packs, where each pack is already its own product:

| Variant | Option value | Linked product | Resolves to |
| - | - | - | - |
| 1 | `Pack size: 1 Bottle` | `menosoothe-1` | \$69.00 |
| 2 | `Pack size: 3 Bottles` | `menosoothe-3` | \$177.00 |
| 3 | `Pack size: 6 Bottles` | `menosoothe-6` | \$294.00 |

The dashboard product list shows one **MenoSoothe** row instead of three, the storefront
renders one page with a picker, and add-to-cart still submits `menosoothe-3`.

<Note>
  Leave **Linked product** empty for a standalone variant that carries its own price, SKU
  and inventory. Mixing both styles on one product is supported — each variant resolves
  independently.
</Note>

### Field resolution order

For every commercial field the variant's own value wins when set, and the linked
product fills in the rest:

```
price          variant.price          -> linked product.price
retail_price   variant.retail_price   -> linked product.retail_price
sku            variant.sku            -> linked product.sku
units          variant.units          -> linked product.units
image          variant.image          -> linked product.image
code           variant.code           -> linked product.code -> variant id
```

***

## Default Variant

Every product with variants has exactly **one** default — the variant used when no
selection is made. If you do not flag one, the lowest **Position** wins. This guarantees
a product can always be added to a cart without an explicit choice.

***

## Setting Up Variant Options

Before adding variants to a product, create the variant option definitions:

1. Go to **Settings → Products → Variant Options**
2. Create a new option (e.g., `Color` with values: Red, Blue, Green)
3. Repeat for each dimension (e.g., `Size` with values: S, M, L, XL)

***

## Adding Variants to a Product

1. Open the product and go to the **Variants** tab
2. In **Variant Options**, check the options that apply to this product (e.g., Color and Size)
3. In **Product Variants**, click **Add Variant** for each combination
4. For each variant row, fill in:
   * **Code** — Unique variant identifier
   * **Price** — Variant-specific price
   * One field per selected option (e.g., Color, Size)

***

## Per-Variant Pricing

Each variant has its own **Price** field. If left blank, the product's base price is used at checkout.

***

## Variant Option Values (`option_values`)

Each variant stores its option selections as `option_values` — a map of option slug to selected value:

```json theme={null}
{
  "color": "Blue",
  "size": "M"
}
```

This map is available in the template engine as `variant.option_values`.

***

## Variant Attributes

Product Attributes with `applies_to = variant` or `applies_to = both` can store values per variant. These appear in each variant row in the Variants tab and are managed independently.

To set up variant-scoped attributes:

1. Go to **Settings → Products → Product Attributes**
2. Create or edit an attribute and set **Applies To** to `Variant` or `Both`
3. Open any product → Variants tab — variant rows will include inputs for these attributes

See [Product Attributes](/products/product-attributes) for full documentation on the attribute system.

***

## Template Access

Variants are available on the product object:

```
{{ product.variants }}
```

Each variant object:

```
{{ variant.code }}
{{ variant.price | formatPrice:product.currency }}
{{ variant.option_values.color }}
{{ variant.option_values.size }}
```

### Displaying All Variants

```
{% for variant in product.variants %}
  <option value="{{ variant.id }}" data-price="{{ variant.price }}">
    {{ variant.option_values.color }} / {{ variant.option_values.size }}
    — {{ variant.price | formatPrice:product.currency }}
  </option>
{% endfor %}
```

### Accessing Variant Attributes

```
{% set variantAttrDefs = getProductAttributes({ applies_to: 'variant' }) %}
{% for variant in product.variants %}
  {% for def in variantAttrDefs %}
    {{ def.name }}: {{ variant | attr:def.slug }}
  {% endfor %}
{% endfor %}
```


# Subscription Analytics
Source: https://docs.elasticfunnels.io/subscriptions/analytics

Monitor MRR, churn, cohort LTV, and dunning recovery from the subscription analytics dashboard

The subscription analytics dashboard shows recurring revenue, churn, retention, dunning recovery, and customer lifetime value. Navigate to **Reports** → **Subscription Analytics** in the sidebar.

## Summary Cards

The top of the dashboard shows four key metrics:

<CardGroup>
  <Card title="MRR" icon="chart-line">
    Monthly Recurring Revenue — the total of all active subscription amounts, normalized to a monthly value.
  </Card>

  <Card title="Active Subscribers" icon="users">
    The current count of subscriptions with an active status.
  </Card>

  <Card title="Churn Rate" icon="arrow-trend-down">
    The percentage of subscriptions that canceled in the last 30 days relative to the active base.
  </Card>

  <Card title="Avg Customer LTV" icon="money-bill-trend-up">
    Average lifetime revenue per subscriber across all subscription customers.
  </Card>
</CardGroup>

## MRR Trend

A line chart showing Monthly Recurring Revenue over time. Each data point represents the total subscription revenue for that month. Use this to track growth trends and spot seasonal patterns.

## Churn Trend

A dual-series chart with two lines:

* **New Subscriptions** — Count of new subscription purchases per month
* **Cancellations** — Count of subscription cancellations per month

When cancellations consistently exceed new subscriptions, your subscriber base is shrinking.

## Cohort LTV

A heatmap table showing cumulative revenue by acquisition month over a 12-month horizon. Each row is a cohort (customers who first subscribed that month), and each column shows their cumulative revenue at month 1, 2, 3, and so on.

<Tip>
  Cohort analysis reveals retention problems 3–4 months earlier than aggregate churn metrics. If you see a cohort's revenue flatten early compared to others, investigate what changed in your offer or onboarding during that period.
</Tip>

## Dunning Recovery

Recovery metrics for the failed payment retry system:

* **Recovered** — Subscriptions that were in dunning and successfully re-charged
* **Lost** — Subscriptions that exhausted all retry attempts and were canceled
* **Recovery Rate** — Recovered ÷ (Recovered + Lost) as a percentage

<Info>
  A recovery rate below 50% usually means your dunning emails need work or your retry timing should be adjusted. See [Subscription Emails & Dunning](/subscriptions/emails-and-dunning) for configuration.
</Info>

## Filters

All charts and metrics can be filtered by:

* **Date range** — Analyze a specific time period
* **Merchant** — Focus on a single merchant
* **Product** — Filter by product code
* **Show test** — Include or exclude test transactions


# Subscription Emails & Dunning
Source: https://docs.elasticfunnels.io/subscriptions/emails-and-dunning

Configure lifecycle emails for renewals, failed payments, pre-renewal reminders, pauses, and cancellations

ElasticFunnels sends automated emails at key points in the subscription lifecycle. The dunning system automatically retries failed charges on a configurable schedule and escalates to your call center if needed.

## Subscription Email Templates

Five subscription-specific email templates are available:

<CardGroup>
  <Card title="Renewal Success" icon="circle-check">
    Sent after a successful subscription charge. Confirms the renewal and shows the next billing date.
  </Card>

  <Card title="Renewal Failed" icon="circle-exclamation">
    Sent when a charge fails. Supports retry-aware messaging so the tone escalates with each attempt.
  </Card>

  <Card title="Pre-Renewal Reminder" icon="bell">
    Sent 3 days before the next charge. Gives customers time to update their card or make changes.
  </Card>

  <Card title="Subscription Paused" icon="circle-pause">
    Confirms that billing has been paused. Shows the resume date if one is set.
  </Card>

  <Card title="Subscription Canceled" icon="circle-xmark">
    Confirms cancellation. Includes a soft win-back CTA.
  </Card>
</CardGroup>

### Retry-Aware Dunning Emails

The renewal failed template can show different messaging based on how many retry attempts have occurred, using `@if` directives in the template editor:

```
@if(subscription.retry_count eq 1)
  We had trouble processing your payment. Don't worry — we'll try again soon.
@elseif(subscription.retry_count eq 3)
  Your payment could not be processed. Please update your payment method.
@elseif(subscription.retry_count gte 5)
  Final notice: Your subscription will be canceled unless you update your payment method.
@endif
```

This lets you start gentle and escalate the urgency as retries continue.

### Template Variables

All subscription email templates receive the standard purchase data (products, amounts, customer info) plus these subscription-specific fields:

| Variable | Available In |
| - | - |
| `subscription.cycle_number` | All templates |
| `subscription.next_charge_at` | Renewal success, pre-renewal |
| `subscription.frequency_label` | All templates |
| `subscription.retry_count` | Renewal failed |
| `subscription.next_retry_date` | Renewal failed |
| `subscription.card_last4` | Renewal failed |
| `subscription.paused_at` | Paused |
| `subscription.resume_at` | Paused |
| `subscription.canceled_at` | Canceled |
| `subscription.cancel_reason` | Canceled |

## Setting Up Subscription Emails

<Steps>
  <Step title="Open your merchant settings">
    Go to **Settings** → **Merchants** and click to edit your NMI or Stripe merchant.
  </Step>

  <Step title="Go to the Email tab">
    Switch to the **Email** tab. You'll see the standard order email section, plus two new sections: **Subscription Emails** and **Dunning Configuration**.
  </Step>

  <Step title="Create email templates">
    In the **Subscription Emails** section, click **Create** next to each template type. This generates a pre-built template you can customize in the email editor. Then select the template from the dropdown.
  </Step>

  <Step title="Configure dunning settings">
    In the **Dunning Configuration** section, set your retry schedule and escalation rules.
  </Step>
</Steps>

<Warning>
  Subscription emails require an **Email Integration** (Mailgun, Sendgrid, or Mailrelay) configured on the merchant. Without one, no emails will be sent.
</Warning>

<Note>
  The Subscription Emails and Dunning Configuration sections only appear for **NMI** and **Stripe** merchants, since those gateways can manage subscription billing inside ElasticFunnels.
</Note>

## Dunning Configuration

Dunning is the process of retrying failed subscription charges. When a renewal fails, the subscription enters a retry cycle according to your schedule.

| Setting | Description | Default |
| - | - | - |
| **Max Retries** | Maximum retry attempts before auto-canceling | 6 |
| **Retry Schedule** | Day intervals between retries | 1, 3, 5, 7, 10, 14 |
| **Callcenter Escalation After Retry #** | Escalate to callcenter after this many retries | 3 (set to 0 to disable) |
| **Send to Callcenter on Cancel** | Route cancellation events to callcenter | Off |

<Info>
  The **Callcenter Escalation After Retry #** and **Send to Callcenter on Cancel** settings decide *whether* to send a call center event for that merchant. The integration controls *which* providers receive it, *when* they receive it, and *which* decline codes qualify. See [External Call Center Integrations](/integrations/callcenters) for the per-event configuration.
</Info>

### How the Retry Schedule Works

The retry schedule defines the number of days after the initial failure for each retry attempt. With the default schedule `1, 3, 5, 7, 10, 14`:

1. **Day 1** — First retry
2. **Day 3** — Second retry
3. **Day 5** — Third retry (callcenter escalation triggers here if configured at 3)
4. **Day 7** — Fourth retry
5. **Day 10** — Fifth retry
6. **Day 14** — Sixth and final retry

If all retries are exhausted, the subscription is automatically canceled.

<Tip>
  A healthy dunning recovery rate is 60–80%. If yours is below 50%, try adjusting your retry timing, ensure your renewal-failed emails have a clear "Update Payment Method" button, and consider enabling callcenter escalation.
</Tip>

## Pre-Renewal Reminders

Pre-renewal emails are sent automatically **3 days** before the next scheduled charge to customers with an active subscription and a valid email address.

<Info>
  Pre-renewal emails are recommended for legal compliance in some jurisdictions (e.g., FTC negative-option guidelines in the US).
</Info>

## Where Events Go

When a dunning event fires (renewal failed, cancel, winback), it's routed through three layers:

1. **Subscription emails** — the templates described above, sent to the customer directly.
2. **Merchant-level callcenter gate** — the **Callcenter Escalation After Retry #** / **Send to Callcenter on Cancel** settings decide if a call-center send is attempted.
3. **Per-integration event config** — each [external call-center integration](/integrations/callcenters) decides which events it actually receives, how long to wait before sending, and which decline codes to filter.

## Further reading

For detailed documentation on email template design, available variables, and editing, see the dedicated [Emails](/emails/overview) section:

* [Email Templates Overview](/emails/overview) — How to create and edit emails
* [Template Variables](/emails/template-variables) — Complete variable reference
* [Subscription Emails](/emails/subscription-emails) — Detailed guide for all subscription templates
* [Dunning](/emails/dunning) — Deep dive on dunning configuration and escalation


# Subscriptions Overview
Source: https://docs.elasticfunnels.io/subscriptions/overview

Manage recurring subscriptions, view billing history, and take admin actions from the CRM

ElasticFunnels can bill recurring products on schedule. Use the subscription screens to review billing status, open a customer’s billing history, and take admin actions like pause, cancel, force bill, or change the next charge date.

## Subscription Statuses

| Status | Meaning |
| - | - |
| **Active** | Subscription is being billed on schedule |
| **Trial** | Customer is in a free trial period before their first charge |
| **Paused** | Billing is temporarily stopped; resumes later |
| **Past Due** | A renewal charge failed; retries are in progress |
| **Canceled** | Subscription has been terminated |

## Viewing Subscriptions

Go to **Reports** → **Subscriptions** in the sidebar.

### Quick Access Tabs

Use the tabs at the top to filter by status: **All**, **Active**, **Trial**, **Paused**, **Past Due**, **Canceled**. Each tab shows the count of matching subscriptions.

### Columns

* **Status** — Color-coded badge
* **Customer** — Name and email
* **Product** — Subscription product name
* **Amount** — Recurring charge amount
* **Frequency** — Billing interval (Monthly, Weekly, Daily, Yearly)
* **Cycle #** — How many successful charges have occurred
* **Next Charge** — Date of the next scheduled billing
* **Started** — Original purchase date
* **Gateway** — Payment gateway used

### Filters

Narrow the list using the filter bar: **Email**, **Merchant**, **Product Code**, and **Date Range**.

## Subscription Detail Drawer

Click any subscription row to open the detail drawer.

### Tabs

<Tabs>
  <Tab title="Overview">
    Product name, frequency, status, gateway, and customer address. If the subscription has a trial period, trial details are shown here.
  </Tab>

  <Tab title="Billing History">
    Timeline of all charges — successful and failed — with amounts, dates, and gateway responses.
  </Tab>

  <Tab title="Changes">
    Audit log of modifications: upgrades, pauses, resumes, and amount changes.
  </Tab>

  <Tab title="Emails">
    Log of subscription-related emails sent to this customer.
  </Tab>
</Tabs>

### Admin Actions

Action buttons appear at the bottom of the drawer:

* **Cancel** — Terminate the subscription
* **Pause** — Temporarily stop billing
* **Resume** — Restart a paused subscription
* **Skip Next Charge** — Move the next scheduled billing forward by one cycle without charging now
* **Force Bill** — Trigger an immediate charge attempt
* **Change Date** — Set a new next billing date (opens a date picker)
* **Reactivate** — Restart a canceled or past-due subscription
* **Edit Pricing** — Adjust the recurring charge amount, shipping, and discount for the subscription

<Note>
  Actions are context-aware. For example, **Resume** only appears for paused subscriptions, and **Reactivate** only appears for canceled or past-due subscriptions.
</Note>

### Edit Pricing

The **Edit Pricing** action opens a modal where you can adjust:

| Field | Description |
| - | - |
| **Amount** | The recurring charge per cycle |
| **Shipping Amount** | Shipping cost per cycle |
| **Discount Type** | Percentage or fixed amount |
| **Discount Value** | The percentage or dollar amount of the discount |

Changes take effect on the next billing cycle. The discount amount is calculated automatically based on the type and value.

### Bulk Actions

On the **Subscriptions** list, select multiple rows with the checkboxes, then use the bulk action menu:

* **Cancel Selected** — Cancel all selected subscriptions
* **Pause Selected** — Pause billing for all selected subscriptions
* **Force Bill Selected** — Run an immediate billing attempt for each selected subscription

## Subscription Events in Conversions

Subscription lifecycle events also appear in the main conversions list at **Reports** → **Conversions**. Use these quick access tabs to filter them:

* **Sub Cancel** — Subscription cancellations
* **Renewal** — Successful subscription renewals
* **Renewal Failed** — Failed renewal attempts

Purchase conversions that are subscription renewals display a small purple **Recurring** badge. You can also use the **Subscription Only** checkbox filter to show only subscription-related conversions.

## Automation Triggers

Subscription events can trigger automations (email sequences, webhooks) through the funnel automation builder:

* **Subscription Cancel** — Fires on cancellation
* **Subscription Change** — Fires on product or amount changes
* **Subscription Renewal** — Fires on successful renewals
* **Subscription Renewal Failed** — Fires on failed renewals
* **Subscription Reactivate** — Fires on reactivation
* **Subscription Winback** — Fires 30 days after cancellation for re-engagement flows

## Setting Up Subscription Products

To make a product recurring:

1. Go to **Settings** → **Products**
2. Open a product and enable **Is Subscription**
3. Set the **Frequency** and **Frequency Unit** (e.g., every 1 month)
4. Optionally configure a **Trial Period** (in days) and **First Charge Free**

#### Subscription tiers (optional)

Products can expose **multiple subscription tiers** with different intervals and prices, for example good / better / best:

1. On the same product, enable **Is Subscription** and set the base frequency as usual.
2. In the **Subscription tiers** section, turn on **Enable subscription tiers**.
3. Click **Add tier** for each option. For each tier, set:
   * **Tier ID** — Stable identifier (for example `monthly`, `quarterly`)
   * **Interval** and **Interval count** — How often this tier bills
   * **Price** — Recurring amount for that tier
   * **Label** — Customer-facing name for checkout
4. Save the product.

#### Stepped Pricing (optional)

Subscription products can have **stepped pricing** — the recurring charge changes after a set number of billing cycles. This is useful for introductory pricing, loyalty discounts, or tiered retention strategies.

1. Open the product under **Settings** → **Products**.
2. Ensure **Is Subscription** is enabled.
3. In the **Stepped Pricing** section, toggle it on.
4. Click **Add Step** for each pricing tier. For each step, set:
   * **From Cycle** — The cycle number this price starts at
   * **To Cycle** — The cycle number this price ends at (leave empty for "forever")
   * **Price** — The recurring charge amount during these cycles
5. Save the product.

Example: charge $19.99/mo for cycles 1-3, then $14.99/mo from cycle 4 onward.

#### Prepaid Options (optional)

Subscription products can offer **prepaid discounts** where customers pay upfront for 3, 6, or 12 months at a reduced rate:

1. Open the product under **Settings** → **Products**.
2. Ensure **Is Subscription** is enabled.
3. Set the **3-Month Discount (%)**, **6-Month Discount (%)**, and/or **12-Month Discount (%)** fields.
4. Save. Checkout will offer these prepaid options to customers.

#### Subscribe & Save (optional)

Subscription products can show a **Subscribe & Save** discount so the recurring price is lower than the one-time purchase price:

1. Open the product under **Settings** → **Products**.
2. Ensure **Is Subscription** is enabled.
3. Set **Subscribe & save discount (%)** to the percentage off the one-time price you want for subscribers (for example `10` for 10% off).
4. Save the product. Checkout can display the savings versus the one-time price based on this field.

## Recurring Coupons

Coupons can be configured to apply to recurring subscription charges, not just the initial purchase:

1. Go to **Settings** → **Products** → **Coupons** tab.
2. Create or edit a coupon.
3. Under **Recurring Subscription Mode**, choose:
   * **First purchase only** — Discount applies only to the initial order (default).
   * **All recurring charges** — Discount applies to every renewal indefinitely.
   * **Limited recurring cycles** — Discount applies for a set number of renewals. Set the **Number of cycles** field.
4. Save.

The recurring coupon logic is enforced during billing. The subscription detail drawer shows the applied coupon info, including the recurring mode.

## Brand Subscription Settings

Global subscription policies are configured under **Settings** → **Subscriptions**:

| Setting | Description |
| - | - |
| **Cancellation Policy** | Immediate, end of period, or admin only |
| **Grace Period (days)** | Days after failed payment before cancellation |
| **Max Billing Cycles** | Automatically cancel after N cycles (0 = unlimited) |
| **Allow Pause** | Let customers pause their subscription |
| **Allow Skip** | Let customers skip the next charge |
| **Allow Swap Product** | Let customers switch to a different subscription product |
| **Allow Change Date** | Let customers change their next billing date |
| **Customer Self-Service** | Enable the customer-facing subscription management portal |

### Default Email Templates

On the same settings page, assign default email templates for subscription events. These serve as fallbacks when a merchant-specific template is not configured:

* Purchase confirmation
* Renewal success
* Renewal failed / dunning
* Subscription paused
* Subscription canceled

Merchant-level email template assignments (on the Merchant detail page → Email tab) override these brand-level defaults.

## Subscription Analytics

Subscription dashboard cards include:

* **Net Revenue Retention (NRR)** — Tracks MRR growth from existing subscribers over time, including expansion, contraction, and churn.
* **Subscription KPIs** — A summary card showing Active Subscriptions, MRR, Churn Rate, and Average LTV with period-over-period deltas.

Add these cards via the dashboard builder under the **Subscriptions** category.

## Export & Bulk Operations

### Export

From the Subscriptions list, click **Export** to generate a CSV file. You can export all filtered results or just selected rows. You'll receive an email with a download link when the export is ready.

### Bulk Actions

Select multiple subscriptions and use:

* **Cancel Selected** — Cancel with an optional reason
* **Pause Selected** — Pause billing for all selected
* **Force Bill Selected** — Trigger immediate charge attempts


# Retention Offers
Source: https://docs.elasticfunnels.io/subscriptions/retention-offers

Reduce voluntary churn with exit surveys and reason-specific save offers like discounts, pauses, and downgrades

Retention offers intercept cancellation requests with reason-specific save offers. Use them to give customers a clear alternative before the subscription is canceled.

## How It Works

<Steps>
  <Step title="Customer requests cancellation">
    Through the self-service portal or via a call center agent.
  </Step>

  <Step title="Exit survey">
    The customer is asked why they want to cancel, choosing from your configured reasons.
  </Step>

  <Step title="Save offer">
    Based on the reason, the system presents a targeted offer — a discount, a pause, or a downgrade.
  </Step>

  <Step title="Accept or decline">
    If accepted, the offer is applied automatically. If declined, the cancellation proceeds.
  </Step>
</Steps>

## Configuring Retention Offers

Retention offers are configured per merchant:

1. Go to **Settings** → **Merchants** and edit your merchant
2. Find the **Retention Offers** section
3. Toggle **Enable Retention Offers** on
4. Add your **Exit Survey Reasons** (the list of cancellation reasons customers can choose from)
5. For each reason, configure a **Save Offer**

### Exit Survey Reasons

Common examples:

* Too expensive
* Not using it enough
* Found a better alternative
* Product quality issues
* Technical problems

### Offer Types

<CardGroup>
  <Card title="Discount" icon="percent">
    Applies a percentage discount for a set number of billing cycles. After the discount period, full pricing resumes.
  </Card>

  <Card title="Pause" icon="circle-pause">
    Pauses billing for a set number of days. The customer isn't charged during the pause, and billing resumes automatically.
  </Card>

  <Card title="Downgrade" icon="arrow-down">
    Switches the subscription to a lower-tier product.
  </Card>
</CardGroup>

### Offer Settings

For each exit survey reason, you can configure:

| Setting | Description | Example |
| - | - | - |
| **Offer Type** | Discount, pause, or downgrade | Discount |
| **Offer Value** | Discount percentage or pause days | 20 |
| **Offer Label** | Customer-facing message | "Stay and get 20% off for 3 months" |
| **Duration (cycles)** | How many billing cycles the offer lasts | 3 |
| **Product** | For downgrades: the product to switch to | Basic Plan |

### Example Configuration

For the reason "Too expensive":

* **Type**: Discount
* **Value**: 20%
* **Label**: "Stay and get 20% off your next 3 months"
* **Duration**: 3 cycles

For "Not using it enough":

* **Type**: Pause
* **Value**: 30 days
* **Label**: "Take a 30-day break instead of canceling"

## Agent-Assisted Retention

The same retention offers are available to call center agents in the **Customer Service** interface. Agents see the same offers and can apply them on the customer's behalf during a call.

<Info>
  See [Customer Service](/callcenter/customer-service) for how agents use retention offers during calls.
</Info>

## Callcenter Escalation

If you have an external call center integration configured, you can automatically route cancellation requests to your call center team for a retention attempt before confirming. Enable **Send to Callcenter on Cancel** in the merchant's [dunning configuration](/subscriptions/emails-and-dunning#dunning-configuration).