Goals & Revenue

The Goals and Revenue API lets you read goal conversion data, create server-side goal events, view revenue metrics, and record payment transactions. These endpoints are essential for tracking conversions and attributing revenue to visitors.

Info

POST endpoints (/api/v1/goals and /api/v1/payments) require an API key with Read & Write permissions. Read-only API keys will receive a 403 Forbidden response.

Goals

GET /api/v1/goals

Returns a list of all goals for your website with conversion statistics for the given date range. Each goal includes the number of unique visitors who completed it, total completions, and the conversion rate.

Parameter	Type	Required	Description
`site_id`	string	Yes	Your website ID
`start`	string	No	ISO 8601 start date. Default: 30 days ago
`end`	string	No	ISO 8601 end date. Default: now
`timezone`	string	No	IANA timezone. Default: UTC
`limit`	number	No	Results limit, 1–1000. Default: 100

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/goals?site_id=ds_abc123&start=2026-03-01&end=2026-03-26"

{
  "results": [
    {
      "goal_name": "signup",
      "unique_visitors": 340,
      "completion_count": 412,
      "conversion_rate": 0.027
    },
    {
      "goal_name": "purchase",
      "unique_visitors": 85,
      "completion_count": 92,
      "conversion_rate": 0.007
    },
    {
      "goal_name": "newsletter_subscribe",
      "unique_visitors": 210,
      "completion_count": 210,
      "conversion_rate": 0.017
    }
  ],
  "meta": {
    "site_id": "ds_abc123",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z"
  }
}

POST /api/v1/goals

Creates a server-side goal completion event. Use this to track conversions that happen on your backend (e.g., successful payments, account activations) rather than in the browser. Requires an API key with write scope.

Field	Type	Required	Description
`site_id`	string	Yes	Your website ID (query parameter)
`name`	string	Yes	Goal name (e.g., `signup`, `purchase`)
`visitor_id`	string	Yes	The visitor to attribute this goal to
`url`	string	No	URL where the goal occurred
`metadata`	object	No	Arbitrary key-value data to attach to the event

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "signup", "visitor_id": "v_8f3a2b1c", "url": "https://app.example.com/welcome", "metadata": {"plan": "pro"}}' \
  "https://datasaas.co/api/v1/goals?site_id=ds_abc123"

{
  "results": {
    "created": true,
    "goal_name": "signup"
  },
  "meta": {
    "site_id": "ds_abc123"
  }
}

GET /api/v1/goals/:name/completions

Returns a list of individual completions for a specific goal. Each completion includes the visitor who completed it, along with geographic and device information. The :name parameter is the goal name (e.g., signup).

Parameter	Type	Required	Description
`site_id`	string	Yes	Your website ID
`:name`	string	Yes	Goal name (URL path parameter)
`start`	string	No	ISO 8601 start date. Default: 30 days ago
`end`	string	No	ISO 8601 end date. Default: now
`timezone`	string	No	IANA timezone. Default: UTC
`limit`	number	No	Results limit, 1–1000. Default: 100

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/goals/signup/completions?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"

{
  "results": [
    {
      "visitor_id": "v_8f3a2b1c",
      "completed_at": "2026-03-25T14:05:00Z",
      "source": "google.com",
      "country": "United States",
      "city": "San Francisco",
      "browser": "Chrome",
      "os": "macOS",
      "device_type": "desktop"
    },
    {
      "visitor_id": "v_9d4c3e2f",
      "completed_at": "2026-03-24T09:30:00Z",
      "source": "twitter.com",
      "country": "Germany",
      "city": "Berlin",
      "browser": "Firefox",
      "os": "Linux",
      "device_type": "desktop"
    }
  ],
  "meta": {
    "site_id": "ds_abc123",
    "goal_name": "signup",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z",
    "limit": 10
  }
}

Revenue

GET /api/v1/revenue

Returns an overview of revenue metrics for your website within the given date range, including total revenue, monthly recurring revenue (MRR), and conversion rate. All amounts are in dollars (not cents).

Parameter	Type	Required	Description
`site_id`	string	Yes	Your website ID
`start`	string	No	ISO 8601 start date. Default: 30 days ago
`end`	string	No	ISO 8601 end date. Default: now
`timezone`	string	No	IANA timezone. Default: UTC

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/revenue?site_id=ds_abc123&start=2026-03-01&end=2026-03-26"

{
  "results": {
    "total_revenue": 24500.00,
    "mrr": 8200.00,
    "conversion_rate": 0.032
  },
  "meta": {
    "site_id": "ds_abc123",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z",
    "timezone": "UTC"
  }
}

Note

Revenue amounts are returned in dollars, not cents. For example, 24500.00 represents $24,500.00 USD.

GET /api/v1/revenue/timeseries

Returns revenue data broken down over time by the specified granularity. Each data point includes new revenue and refund amounts.

Parameter	Type	Required	Description
`site_id`	string	Yes	Your website ID
`start`	string	No	ISO 8601 start date. Default: 30 days ago
`end`	string	No	ISO 8601 end date. Default: now
`timezone`	string	No	IANA timezone. Default: UTC
`granularity`	string	No	One of `hour`, `day`, `week`, `month`. Default: `day`

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/revenue/timeseries?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&granularity=day"

{
  "results": [
    { "period": "2026-03-01", "new_revenue": 1200.00, "refund_revenue": 0.00 },
    { "period": "2026-03-02", "new_revenue": 850.00, "refund_revenue": 49.99 },
    { "period": "2026-03-03", "new_revenue": 1500.00, "refund_revenue": 0.00 }
  ],
  "meta": {
    "site_id": "ds_abc123",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z",
    "granularity": "day"
  }
}

POST /api/v1/payments

Creates a payment record and attributes it to a visitor. Use this to manually record payments from custom billing systems or providers not natively supported. Requires an API key with write scope.

Field	Type	Required	Description
`site_id`	string	Yes	Your website ID (query parameter)
`visitor_id`	string	Yes	The visitor to attribute payment to
`amount`	number	Yes	Payment amount in dollars (e.g., `99.00`)
`currency`	string	Yes	ISO 4217 currency code (e.g., `USD`)
`transaction_id`	string	Yes	Your unique transaction identifier
`payment_type`	string	No	One of `one_time`, `recurring`, `refund`. Default: `one_time`
`product_name`	string	No	Name of the product or plan
`paid_at`	string	No	ISO 8601 timestamp. Default: now

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"visitor_id": "v_8f3a2b1c", "amount": 99.00, "currency": "USD", "transaction_id": "txn_abc123", "payment_type": "recurring", "product_name": "Pro Plan"}' \
  "https://datasaas.co/api/v1/payments?site_id=ds_abc123"

{
  "results": {
    "created": true,
    "transaction_id": "txn_abc123"
  },
  "meta": {
    "site_id": "ds_abc123"
  }
}

Visitors

Realtime