Create a funnel

Create a multistep conversion funnel with the Clics TypeScript SDK: steps, filters, and conversion window.

Creates a multistep funnel for drop-off analysis. Funnels are optional, you only need them when you want to see how visitors progress through a sequence of actions.

Each funnel needs at least two steps and a conversion window that defines how long a visitor has to complete all steps after entering step 1.

Parameters

Field	Required	Description
`projectId`	Yes	Parent project
`body.name`	Yes	Display name
`body.conversionWindow`	Yes	`{ value: number, unit: string }`; `value` is a positive integer, e.g. `{ value: 7, unit: "days" }`
`body.steps`	Yes	Array of at least 2 steps (see below)
`body.envId`	No	`production` (default) or `development`

Step structure

Each step requires:

Field	Required	Description
`name`	Yes	Step label (e.g. “Cart”, “Purchase”)
`filters`	Yes	At least one filter with `filterType`, `operator`, and `values`

Conversion window units: seconds, minutes, hours, days, weeks, months

Filter types: page, event, country, device, browser, os, hostname, referrer, utm_source, utm_medium, utm_campaign, utm_term, utm_content

Operators: is, is_not, contains, not_contains

Signature

clics.funnels.createFunnel(request, options?)

Example

import { Clics } from "@clicsdev/sdk";

const clics = new Clics({
  apiKey: process.env.CLICS_API_KEY!,
});

const result = await clics.funnels.createFunnel({
  projectId: "proj_xxx",
  body: {
    name: "Checkout",
    envId: "production",
    conversionWindow: { value: 7, unit: "days" },
    steps: [
      {
        name: "Cart",
        filters: [
          { filterType: "page", operator: "is", values: ["/cart"] },
        ],
      },
      {
        name: "Purchase",
        filters: [
          { filterType: "page", operator: "is", values: ["/thanks"] },
        ],
      },
    ],
  },
});

Event-based step:

{
  name: "Added to cart",
  filters: [
    { filterType: "event", operator: "is", values: ["add_to_cart"] },
  ],
}

What it returns

The created Funnel object. Save its id to fetch statistics, update, or delete it later.

{
  id: "funnel_xxx",
  projectId: "proj_xxx",
  envId: "production",
  name: "Checkout",
  conversionWindow: { value: 7, unit: "days" },
  steps: [
    { name: "Cart", filters: [{ filterType: "page", operator: "is", values: ["/cart"] }] },
    { name: "Paid", filters: [{ filterType: "event", operator: "is", values: ["purchase"] }] },
  ],
  createdAt: 1_754_000_000_000,
}

Field	Type	Description
`id`	`string`	Stable funnel ID, for example `funnel_xxx`
`projectId`	`string`	Parent project ID
`envId`	`"production" \| "development"`	Environment in which the funnel evaluates traffic
`name`	`string`	Funnel label shown in Dashboard
`conversionWindow`	`{ value, unit }`	Final time allowed to complete the journey after step 1
`steps`	`Array<{ name, filters }>`	Complete ordered funnel definition. Each filter has `filterType`, `operator`, and `values`
`createdAt`	`number`	Creation timestamp

Notes

Test funnels in development before creating them in production
Step order matters: visitors must match steps in sequence within the conversion window
An event step only matches events that the tracker is already sending; see Custom events

API reference

See Create a funnel for request and response schemas, status codes, and error types.