Formtoro
API Reference

Revenue & attribution

Attribution, discounts, UTM revenue, and customer LTV.

Attribution breakdown

GET
/v1/attribution

Authorization

apiKey
AuthorizationBearer <token>

A Formtoro API key minted in Settings → Connections. A key carries one or more scopes; an endpoint refuses a key that lacks its required scope with 403 insufficient_scope. Scopes:

  • analytics:read — all aggregate read endpoints.
  • customers:read — customer-level lifetime value.
  • forms:write — create and edit forms (drafts). Grantable only by a member who holds the Form-editing permission.
  • discounts:read — read discount definitions. Grantable only by a member who holds the Discounts-view permission.

In: header

Query Parameters

range?string

Time window. Shorthand (7d/30d/90d), an ISO pair (2026-01-01..2026-01-31), or a single ISO day. Omitted → last 30 days.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/attribution?range=30d"
{  "meta": {    "requestId": "string",    "shopId": "string",    "credentialId": "string",    "range": {      "from": "2019-08-24T14:15:22Z",      "to": "2019-08-24T14:15:22Z"    }  },  "data": [    {}  ]}

Daily attribution metrics

GET
/v1/attribution/daily

Authorization

apiKey
AuthorizationBearer <token>

A Formtoro API key minted in Settings → Connections. A key carries one or more scopes; an endpoint refuses a key that lacks its required scope with 403 insufficient_scope. Scopes:

  • analytics:read — all aggregate read endpoints.
  • customers:read — customer-level lifetime value.
  • forms:write — create and edit forms (drafts). Grantable only by a member who holds the Form-editing permission.
  • discounts:read — read discount definitions. Grantable only by a member who holds the Discounts-view permission.

In: header

Query Parameters

range?string

Time window. Shorthand (7d/30d/90d), an ISO pair (2026-01-01..2026-01-31), or a single ISO day. Omitted → last 30 days.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/attribution/daily?range=30d"
{  "meta": {    "requestId": "string",    "shopId": "string",    "credentialId": "string",    "range": {      "from": "2019-08-24T14:15:22Z",      "to": "2019-08-24T14:15:22Z"    }  },  "data": [    {}  ]}

Discount-code performance

GET
/v1/discounts/performance

Authorization

apiKey
AuthorizationBearer <token>

A Formtoro API key minted in Settings → Connections. A key carries one or more scopes; an endpoint refuses a key that lacks its required scope with 403 insufficient_scope. Scopes:

  • analytics:read — all aggregate read endpoints.
  • customers:read — customer-level lifetime value.
  • forms:write — create and edit forms (drafts). Grantable only by a member who holds the Form-editing permission.
  • discounts:read — read discount definitions. Grantable only by a member who holds the Discounts-view permission.

In: header

Query Parameters

range?string

Time window. Shorthand (7d/30d/90d), an ISO pair (2026-01-01..2026-01-31), or a single ISO day. Omitted → last 30 days.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/discounts/performance?range=30d"
{  "meta": {    "requestId": "string",    "shopId": "string",    "credentialId": "string",    "range": {      "from": "2019-08-24T14:15:22Z",      "to": "2019-08-24T14:15:22Z"    }  },  "data": [    {}  ]}

Signups and revenue by UTM

GET
/v1/revenue/by-utm

Authorization

apiKey
AuthorizationBearer <token>

A Formtoro API key minted in Settings → Connections. A key carries one or more scopes; an endpoint refuses a key that lacks its required scope with 403 insufficient_scope. Scopes:

  • analytics:read — all aggregate read endpoints.
  • customers:read — customer-level lifetime value.
  • forms:write — create and edit forms (drafts). Grantable only by a member who holds the Form-editing permission.
  • discounts:read — read discount definitions. Grantable only by a member who holds the Discounts-view permission.

In: header

Query Parameters

dimension*string
  • campaign — utmSource × utmCampaign with submissions, converted submissions, orders, conversion rate, and revenue (UtmCampaignRow)
  • attribution — attribution type × utmSource × utmCampaign with orders and revenue (AttributionUtmRow)
  • hierarchy — utmSource / utmCampaign / utmMedium / utmTerm / utmContent with orders and revenue (UtmHierarchyRow)

Value in

  • "campaign"
  • "attribution"
  • "hierarchy"
range?string

Time window. Shorthand (7d/30d/90d), an ISO pair (2026-01-01..2026-01-31), or a single ISO day. Omitted → last 30 days.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/revenue/by-utm?dimension=campaign&range=30d"
{  "data": {    "dimension": "campaign",    "rows": [      {        "utmSource": "facebook",        "utmCampaign": "spring_sale",        "submissionCount": 412,        "convertedSubmissions": 37,        "attributedOrders": 41,        "attributedRevenueCents": 318500,        "conversionRate": 8.98,        "grossRevenueCents": 318500,        "totalRefundedCents": 12000,        "netRevenueCents": 306500      }    ]  },  "meta": {    "requestId": "req_019e73ce-1968-71ca-ae57-dbd8084cee79",    "shopId": "example.myshopify.com",    "credentialId": "cred_019e73c0",    "range": {      "from": "2026-08-17T00:00:00.000Z",      "to": "2026-09-16T23:59:59.999Z"    }  }}

Ad spend and ROAS by campaign

GET
/v1/ads/spend

Authorization

apiKey
AuthorizationBearer <token>

A Formtoro API key minted in Settings → Connections. A key carries one or more scopes; an endpoint refuses a key that lacks its required scope with 403 insufficient_scope. Scopes:

  • analytics:read — all aggregate read endpoints.
  • customers:read — customer-level lifetime value.
  • forms:write — create and edit forms (drafts). Grantable only by a member who holds the Form-editing permission.
  • discounts:read — read discount definitions. Grantable only by a member who holds the Discounts-view permission.

In: header

Query Parameters

range?string

Time window. Shorthand (7d/30d/90d), an ISO pair (2026-01-01..2026-01-31), or a single ISO day. Omitted → last 30 days.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/ads/spend?range=30d"
{  "data": {    "rows": [      {        "provider": "meta",        "campaignId": "120210000000000001",        "campaignName": "Spring Sale — Prospecting",        "currency": "USD",        "spend": 1250.5,        "impressions": 184000,        "clicks": 3120,        "attributedSubmissions": 412,        "attributedOrders": 41,        "attributedNetRevenueCents": 318500,        "revenueCurrency": "USD",        "costPerLead": 3.04,        "costPerAcquisition": 30.5,        "roas": 2.55      },      {        "provider": "meta",        "campaignId": "",        "campaignName": "unattributed",        "currency": "",        "spend": 0,        "impressions": 0,        "clicks": 0,        "attributedSubmissions": 0,        "attributedOrders": 6,        "attributedNetRevenueCents": 41200,        "revenueCurrency": "",        "costPerLead": 0,        "costPerAcquisition": 0,        "roas": 0      }    ],    "attributionCoverage": {      "meta": 100,      "google": null    },    "unavailableProviders": []  },  "meta": {    "requestId": "req_019e73ce-1968-71ca-ae57-dbd8084cee79",    "shopId": "example.myshopify.com",    "credentialId": "cred_019e73c0",    "range": {      "from": "2026-04-01T00:00:00.000Z",      "to": "2026-04-30T23:59:59.999Z"    }  }}

Customer lifetime value

GET
/v1/customers/ltv

Authorization

apiKey
AuthorizationBearer <token>

A Formtoro API key minted in Settings → Connections. A key carries one or more scopes; an endpoint refuses a key that lacks its required scope with 403 insufficient_scope. Scopes:

  • analytics:read — all aggregate read endpoints.
  • customers:read — customer-level lifetime value.
  • forms:write — create and edit forms (drafts). Grantable only by a member who holds the Form-editing permission.
  • discounts:read — read discount definitions. Grantable only by a member who holds the Discounts-view permission.

In: header

Query Parameters

dimension*string
  • form — LTV grouped by form id
  • segment — LTV grouped by response segment

Value in

  • "form"
  • "segment"
range?string

Time window. Shorthand (7d/30d/90d), an ISO pair (2026-01-01..2026-01-31), or a single ISO day. Omitted → last 30 days.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/customers/ltv?dimension=form&range=30d"
{  "meta": {    "requestId": "string",    "shopId": "string",    "credentialId": "string",    "range": {      "from": "2019-08-24T14:15:22Z",      "to": "2019-08-24T14:15:22Z"    }  },  "data": {}}

Shop analytics

Shop-wide analytics across all forms.

Experiments

A/B tests between two forms — inventory and per-arm results.