For the complete documentation index, see llms.txt. For the full corpus, see llms-full.txt. For raw markdown, append .md to this URL or send Accept: text/markdown.

Tracking Goals

Increment and decrement goal counters with metadata

Last updated: May 19, 2026

Basic Increment

Track a goal completion:

typescript

await SessionSightGoals.increment('user-signups');

This increments the goal by 1. The goal must already exist in your SessionSight dashboard.

Custom Amount

Increment by a specific amount. This is how you fire revenue goals:

typescript

await SessionSightGoals.increment('page-views', { amount: 5 });

For revenue goals (kind: 'revenue' at creation), amount is dollars booked. Progress is the sum of amounts and the dashboard renders totals in USD. For count goals (kind: 'count', the default), amount is ignored for progress. Each call counts as one conversion.

Kind is set when the goal is created in the dashboard and is immutable afterward. To change a goal’s kind, delete and recreate it.

Metadata

Attach key-value metadata for context:

typescript

await SessionSightGoals.increment('user-signups', {
  metadata: {
    plan: 'pro',
    source: 'landing-page',
    campaign: 'summer-sale',
  },
});

Decrementing Goals

Subtract from a goal counter. Useful for refunds, cancellations, or inventory adjustments:

typescript

await SessionSightGoals.decrement('inventory');

With a custom amount and metadata:

typescript

await SessionSightGoals.decrement('inventory', {
  amount: 3,
  metadata: { reason: 'refund' },
});

API Reference

`SessionSightGoals.increment(goalId, options?)`

Parameter	Type	Default	Description
`goalId`	`string`	required	The goal ID from your dashboard
`options.sessionId`	`string`	required	Session the goal fire belongs to. Visitor and user identity are resolved from the session on the backend. Use `forRequest(req)` to auto-attach from the `ss_sid` cookie, or thread `sessionId` through out-of-band pipelines (e.g. Stripe metadata).
`options.amount`	`number`	`1`	For revenue goals, dollars booked (summed into progress). For count goals, ignored (each call = 1 conversion).
`options.metadata`	`Record<string, string>`	-	Key-value context

`SessionSightGoals.decrement(goalId, options?)`

Parameter	Type	Default	Description
`goalId`	`string`	required	The goal ID from your dashboard
`options.sessionId`	`string`	required	Session the decrement belongs to (same rules as `increment`)
`options.amount`	`number`	`1`	Amount to decrement by
`options.metadata`	`Record<string, string>`	-	Key-value context

Return Type

Both increment() and decrement() return:

typescript

interface IncrementResult {
  success: boolean;
  error?: string;
}