Skip to main content

​
Funnel Orchestrator

What is a funnel? A funnel is a sequence of pages your customer walks through: landing page → checkout → upsell offer → thank you. The orchestrator manages the order, the navigation, the analytics, and the A/B testing — all in one place.

​
Why Use the Funnel Orchestrator?

Without a funnel, your checkout is a single isolated page. The customer pays and lands on a generic confirmation. That works, but you’re leaving money and insights on the table. With the orchestrator you get:
CapabilityWhat it does
Multi-step flowsChain pages together: checkout → upsell → downsell → thank you
Automatic navigationThe SDK moves the customer to the next step — no manual redirects
Session trackingOne session follows the customer across all steps (device, UTMs, timestamps)
Conversion analyticsSee where customers drop off and which steps convert
A/B testing per stepSplit traffic on any step — different pages, different configs
Automatic routingWhen you save a funnel, routes are mounted/unmounted for you
In short: the orchestrator turns a standalone page into a real sales flow with analytics.

​
Core Concepts (5-minute overview)

​
Funnel = Graph of Nodes and Edges

A funnel is a directed graph: 
[Checkout] ──→ [Upsell Offer] ──→ [Thank You]
   (entry)                          (conversion)
  • Nodes are the steps (checkout page, upsell page, thank you page, etc.)
  • Edges are the connections between steps (what comes after what)

​
Node Types

TypePurpose
checkoutPayment page — collects customer info and processes the order
thankyouConfirmation page — shown after a successful purchase
offer / upsellPost-purchase offer — shown between checkout and thank you
downsellAlternative offer if the customer declines the upsell
landingPre-checkout page (landing page, product page, etc.)

​
What Happens Under the Hood

When you create or update a funnel via the API:
  1. TagadaPay saves the funnel configuration (nodes + edges)
  2. For each step, it automatically mounts the right plugin page at the right URL path
  3. The SDK reads the funnel config at runtime and handles navigation between steps
  4. Analytics events are tracked automatically (views, enters, conversions)
You don’t need to manually mount routes — the funnel orchestrator does it for you.

​
Tutorial: Create Your First Funnel

We’ll create the most common funnel: Checkout → Thank You.

​
Prerequisites

  • A TagadaPay account with an API key
  • A store (you can create one via the API or from the CRM)
  • At least one deployed plugin (the built-in tagada-native checkout is auto-provisioned for you)
If you don’t have a custom plugin deployed, TagadaPay will automatically inject its built-in checkout plugin (tagada-native) into your funnel steps. You can start without deploying anything.

​
Step 1 — Create the Funnel

curl -X POST https://app.tagadapay.com/api/public/v1/funnels \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "store_abc123",
    "config": {
      "name": "My First Funnel",
      "version": "1.0.0",
      "nodes": [
        {
          "id": "step_checkout",
          "name": "Checkout",
          "type": "checkout",
          "isEntry": true,
          "config": {
            "path": "/checkout"
          }
        },
        {
          "id": "step_thankyou",
          "name": "Thank You",
          "type": "thankyou",
          "isConversion": true,
          "config": {
            "path": "/thankyou"
          }
        }
      ],
      "edges": [
        {
          "id": "edge_1",
          "source": "step_checkout",
          "target": "step_thankyou"
        }
      ]
    },
    "isDefault": true
  }'
What just happened:
  • TagadaPay created a funnel with two steps
  • It automatically provisioned the native checkout plugin for both steps
  • Routes were mounted so /checkout and /thankyou resolve to the right pages
  • This funnel is marked as the default — it’s the one used when a customer hits your store’s checkout URL

​
Step 2 — Verify Your Funnel

curl https://app.tagadapay.com/api/public/v1/funnels/FUNNEL_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
The response includes the full config with the auto-injected plugin instance IDs: 
{
  "id": "funnelv2_abc123",
  "name": "My First Funnel",
  "active": true,
  "config": {
    "nodes": [
      {
        "id": "step_checkout",
        "name": "Checkout",
        "type": "checkout",
        "isEntry": true,
        "config": {
          "path": "/checkout",
          "pluginId": "tagada-native",
          "instanceId": "mgwf1ft7iws46-6d4feb54",
          "instanceVersion": "1.0.0"
        }
      }
    ],
    "edges": [...]
  }
}
Notice the pluginId, instanceId, and instanceVersion — TagadaPay injected those automatically because the step type is checkout. You didn’t have to deploy or configure anything.

​
Step 3 — Test with a Preview Session

Preview sessions let you test the funnel without real payments: 
curl -X POST https://app.tagadapay.com/api/public/v1/funnels/FUNNEL_ID/preview-session \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "store_abc123",
    "funnelId": "funnelv2_abc123",
    "stepId": "step_checkout"
  }'
Response: 
{
  "sessionId": "fs_123456789",
  "funnelId": "funnelv2_abc123",
  "stepId": "step_checkout",
  "token": "eyJhbG...",
  "customerId": "cus_preview_123"
}
Use the sessionId and token to load the checkout page in preview mode.

​
Adding an Upsell Step

The real power of funnels comes from post-purchase flows. Let’s add an upsell offer between checkout and thank you. Use the Update Funnel endpoint: 
curl -X PUT https://app.tagadapay.com/api/public/v1/funnels/FUNNEL_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "funnelId": "funnelv2_abc123",
    "storeId": "store_abc123",
    "config": {
      "name": "Checkout with Upsell",
      "version": "1.1.0",
      "nodes": [
        {
          "id": "step_checkout",
          "name": "Checkout",
          "type": "checkout",
          "isEntry": true,
          "config": { "path": "/checkout" }
        },
        {
          "id": "step_offer",
          "name": "Special Offer",
          "type": "offer",
          "config": { "path": "/offer" }
        },
        {
          "id": "step_thankyou",
          "name": "Thank You",
          "type": "thankyou",
          "isConversion": true,
          "config": { "path": "/thankyou" }
        }
      ],
      "edges": [
        { "id": "edge_1", "source": "step_checkout", "target": "step_offer" },
        { "id": "edge_2", "source": "step_offer", "target": "step_thankyou" }
      ]
    }
  }'
The response tells you exactly what the orchestrator did: 
{
  "funnel": { "id": "funnelv2_abc123", "name": "Checkout with Upsell" },
  "operations": [
    { "type": "skip", "stepId": "step_checkout", "status": "completed" },
    { "type": "mount", "stepId": "step_offer", "status": "completed" },
    { "type": "skip", "stepId": "step_thankyou", "status": "completed" }
  ],
  "summary": { "total": 3, "mounted": 1, "unmounted": 0, "swapped": 0, "failed": 0 }
}
The orchestrator:
  • Skipped the checkout and thank you steps (already mounted)
  • Mounted the new offer step at /offer
Your funnel is now: Checkout → Upsell Offer → Thank You.

​
A/B Testing a Step

You can split traffic on any step using variants. Each variant can point to a different page design (different deployment) or the same page with a different config. 
{
  "id": "step_checkout",
  "name": "Checkout",
  "type": "checkout",
  "isEntry": true,
  "splitType": "weighted",
  "variants": [
    {
      "id": "variant_a",
      "label": "Original Design",
      "percentage": 50,
      "config": {
        "path": "/checkout",
        "pluginId": "tagada-native",
        "instanceId": "instance_original"
      }
    },
    {
      "id": "variant_b",
      "label": "New Design",
      "percentage": 50,
      "config": {
        "path": "/checkout",
        "pluginId": "my-custom-checkout",
        "instanceId": "instance_new_design"
      }
    }
  ]
}
Split TypeHow it works
weightedTraffic is split by percentage (e.g., 50/50, 90/10)
geoTraffic is split by visitor region (use the regions field on each variant)
Visitors are sticky — once assigned a variant, they see the same one on return.

​
Step Configuration (Runtime Config)

Each step can have runtime config injected when the page loads — tracking pixels, payment flows, and custom scripts: 
{
  "id": "step_checkout",
  "name": "Checkout",
  "type": "checkout",
  "config": {
    "path": "/checkout",
    "stepConfig": {
      "payment": {
        "paymentFlowId": "pf_stripe_live"
      },
      "scripts": [
        {
          "name": "Facebook Pixel",
          "enabled": true,
          "content": "<script>fbq('track', 'InitiateCheckout');</script>",
          "position": "body-end"
        }
      ],
      "pixels": {
        "facebook": {
          "enabled": true,
          "pixelId": "123456789",
          "events": {
            "PageView": true,
            "InitiateCheckout": true,
            "Purchase": true
          }
        }
      }
    }
  }
}
The step config is available in the Plugin SDK via useStepConfig() or window.__TGD_STEP_CONFIG__. See Step Config & Script Injection for details.

​
Tracking Funnel Events

The SDK tracks events automatically when used inside a funnel. If you need manual tracking (e.g., from a server or external page), use the Track Funnel Step endpoint: 
curl -X POST https://app.tagadapay.com/api/public/v1/funnel-tracking/step \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "convert",
    "storeId": "store_abc123",
    "stepId": "step_thankyou",
    "stepName": "Thank You",
    "stepType": "thankyou",
    "funnelId": "funnelv2_abc123",
    "funnelSessionId": "fs_1234567890_abc123",
    "customerId": "cus_123",
    "isConversionStep": true,
    "orderId": "order_abc",
    "orderAmount": 4999,
    "orderCurrency": "USD"
  }'
Event TypeWhen to use
viewPage was displayed (impression)
enterCustomer navigated to the step
convertCustomer completed the step’s goal (e.g., purchase)
customAny custom event you want to track

​
Debugging a Funnel Session

To inspect what happened in a customer’s session: 
curl https://app.tagadapay.com/api/public/v1/funnel-sessions/SESSION_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
This returns the full session data: current step, furthest step reached, customer history, timestamps, metadata, and resources. Useful for debugging why a customer dropped off or got stuck.

​
Complete API Reference

EndpointMethodWhat it does
/stores/{storeId}/funnelsGETList all funnels for a store
/funnelsPOSTCreate a new funnel
/funnels/{id}GETGet funnel details
/funnels/{funnelId}PUTUpdate funnel (auto-mounts routes)
/funnels/{funnelId}DELETEDelete funnel and clean up routes
/funnels/{funnelId}/preview-sessionPOSTCreate a test session
/funnel-sessions/{sessionId}GETDebug a session
/funnel-tracking/stepPOSTTrack analytics events

​
Recap

1. Create funnel      →  Define nodes (steps) and edges (flow)
2. TagadaPay mounts   →  Routes and plugins are configured automatically
3. Customer visits    →  SDK handles navigation between steps
4. You track results  →  Conversion analytics per step, per variant
5. Iterate            →  Update the funnel, add steps, split test

Plugin SDK

Build the pages that power each step

Hosting & A/B Testing

Host any page and run split tests

Direct Link Guide

Generate checkout URLs from any website

External Page Tracker

Connect external pages to the funnel