FormtoroBack to Formtoro
API Reference

Forms

Form inventory and per-form analytics.

List the shop's forms

GET
/v1/forms

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

limit?integer

Page size. Defaults to 50; values above 200 are clamped to 200; a non-positive or non-numeric value is a 400 (invalid_limit).

cursor?string

Opaque pagination cursor from a previous response's meta.nextCursor. A stale/unknown cursor returns an empty page (never a silent page-one replay).

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/forms"
{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "status": "draft",      "updatedAt": "2019-08-24T14:15:22Z"    }  ],  "meta": {    "requestId": "req_019e73ce-1968-71ca-ae57-dbd8084cee79",    "shopId": "example.myshopify.com",    "credentialId": "cred_019e73c0",    "range": {      "from": "2019-08-24T14:15:22Z",      "to": "2019-08-24T14:15:22Z"    },    "nextCursor": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

Create a new form

POST
/v1/forms

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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/forms" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "schema": {}  }'
{  "meta": {    "requestId": "req_019e73ce-1968-71ca-ae57-dbd8084cee79",    "shopId": "example.myshopify.com",    "credentialId": "cred_019e73c0",    "range": {      "from": "2019-08-24T14:15:22Z",      "to": "2019-08-24T14:15:22Z"    }  },  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "status": "draft",    "updatedAt": "2019-08-24T14:15:22Z"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

Aggregate form conversion funnels

GET
/v1/forms/funnel

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.

form_ids?array<>

Optional comma-separated form UUIDs to include. Max 100 ids. Omit to return every form with events in the requested window.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/forms/funnel?range=30d&form_ids=019e73ce-1968-71ca-ae57-dbd8084cee79%2C019e73ce-1968-71ca-ae57-dbd8084cee7a"
{  "meta": {    "requestId": "req_019e73ce-1968-71ca-ae57-dbd8084cee79",    "shopId": "example.myshopify.com",    "credentialId": "cred_019e73c0",    "range": {      "from": "2019-08-24T14:15:22Z",      "to": "2019-08-24T14:15:22Z"    }  },  "data": [    {      "formId": "126460ed-49b2-4c69-849a-bd8904ec5d8f",      "views": 0,      "subscriptions": 0,      "completions": 0    }  ]}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

Get one form by id

GET
/v1/forms/{id}

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

Path Parameters

id*string

The form's UUID. A non-UUID value resolves to 404, never a 500.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/forms/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "meta": {    "requestId": "req_019e73ce-1968-71ca-ae57-dbd8084cee79",    "shopId": "example.myshopify.com",    "credentialId": "cred_019e73c0",    "range": {      "from": "2019-08-24T14:15:22Z",      "to": "2019-08-24T14:15:22Z"    }  },  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "status": "draft",    "updatedAt": "2019-08-24T14:15:22Z"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

Replace a form's draft

PUT
/v1/forms/{id}

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

Path Parameters

id*string

The form's UUID. A non-UUID value resolves to 404, never a 500.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/v1/forms/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "draft_schema": {}  }'
{  "meta": {    "requestId": "req_019e73ce-1968-71ca-ae57-dbd8084cee79",    "shopId": "example.myshopify.com",    "credentialId": "cred_019e73c0",    "range": {      "from": "2019-08-24T14:15:22Z",      "to": "2019-08-24T14:15:22Z"    }  },  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "status": "draft",    "updatedAt": "2019-08-24T14:15:22Z"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

Form conversion funnel

GET
/v1/forms/{id}/funnel

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

Path Parameters

id*string

The form's UUID. A non-UUID value resolves to 404, never a 500.

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/forms/497f6eca-6276-4993-bfeb-53cbbbba6f08/funnel?range=30d"
{  "meta": {    "requestId": "req_019e73ce-1968-71ca-ae57-dbd8084cee79",    "shopId": "example.myshopify.com",    "credentialId": "cred_019e73c0",    "range": {      "from": "2019-08-24T14:15:22Z",      "to": "2019-08-24T14:15:22Z"    }  },  "data": {}}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

Per-step drop-off

GET
/v1/forms/{id}/steps/dropoff

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

Path Parameters

id*string

The form's UUID. A non-UUID value resolves to 404, never a 500.

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/forms/497f6eca-6276-4993-bfeb-53cbbbba6f08/steps/dropoff?range=30d"
{  "meta": {    "requestId": "req_019e73ce-1968-71ca-ae57-dbd8084cee79",    "shopId": "example.myshopify.com",    "credentialId": "cred_019e73c0",    "range": {      "from": "2019-08-24T14:15:22Z",      "to": "2019-08-24T14:15:22Z"    }  },  "data": [    {}  ]}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

Time-to-complete distribution

GET
/v1/forms/{id}/time-to-complete

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

Path Parameters

id*string

The form's UUID. A non-UUID value resolves to 404, never a 500.

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/forms/497f6eca-6276-4993-bfeb-53cbbbba6f08/time-to-complete?range=30d"
{  "meta": {    "requestId": "req_019e73ce-1968-71ca-ae57-dbd8084cee79",    "shopId": "example.myshopify.com",    "credentialId": "cred_019e73c0",    "range": {      "from": "2019-08-24T14:15:22Z",      "to": "2019-08-24T14:15:22Z"    }  },  "data": [    {}  ]}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

Device-type breakdown

GET
/v1/forms/{id}/devices

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

Path Parameters

id*string

The form's UUID. A non-UUID value resolves to 404, never a 500.

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/forms/497f6eca-6276-4993-bfeb-53cbbbba6f08/devices?range=30d"
{  "meta": {    "requestId": "req_019e73ce-1968-71ca-ae57-dbd8084cee79",    "shopId": "example.myshopify.com",    "credentialId": "cred_019e73c0",    "range": {      "from": "2019-08-24T14:15:22Z",      "to": "2019-08-24T14:15:22Z"    }  },  "data": [    {}  ]}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

New vs returning visitor conversion

GET
/v1/forms/{id}/visitor-conversion

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

Path Parameters

id*string

The form's UUID. A non-UUID value resolves to 404, never a 500.

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/forms/497f6eca-6276-4993-bfeb-53cbbbba6f08/visitor-conversion?range=30d"
{  "meta": {    "requestId": "req_019e73ce-1968-71ca-ae57-dbd8084cee79",    "shopId": "example.myshopify.com",    "credentialId": "cred_019e73c0",    "range": {      "from": "2019-08-24T14:15:22Z",      "to": "2019-08-24T14:15:22Z"    }  },  "data": [    {}  ]}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

Pairwise field-value correlation

GET
/v1/forms/{id}/cross-field

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

Path Parameters

id*string

The form's UUID. A non-UUID value resolves to 404, never a 500.

Query Parameters

fieldA*string

First field id to correlate.

fieldB*string

Second field id to correlate.

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/forms/497f6eca-6276-4993-bfeb-53cbbbba6f08/cross-field?fieldA=string&fieldB=string&range=30d"
{  "meta": {    "requestId": "req_019e73ce-1968-71ca-ae57-dbd8084cee79",    "shopId": "example.myshopify.com",    "credentialId": "cred_019e73c0",    "range": {      "from": "2019-08-24T14:15:22Z",      "to": "2019-08-24T14:15:22Z"    }  },  "data": [    {}  ]}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

Revenue by response value

GET
/v1/forms/{id}/response-revenue

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

Path Parameters

id*string

The form's UUID. A non-UUID value resolves to 404, never a 500.

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/forms/497f6eca-6276-4993-bfeb-53cbbbba6f08/response-revenue?range=30d"
{  "meta": {    "requestId": "req_019e73ce-1968-71ca-ae57-dbd8084cee79",    "shopId": "example.myshopify.com",    "credentialId": "cred_019e73c0",    "range": {      "from": "2019-08-24T14:15:22Z",      "to": "2019-08-24T14:15:22Z"    }  },  "data": [    {}  ]}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

Daily time-series for one form

GET
/v1/forms/{id}/trends

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

Path Parameters

id*string

The form's UUID. A non-UUID value resolves to 404, never a 500.

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/forms/497f6eca-6276-4993-bfeb-53cbbbba6f08/trends?range=30d"
{  "meta": {    "requestId": "req_019e73ce-1968-71ca-ae57-dbd8084cee79",    "shopId": "example.myshopify.com",    "credentialId": "cred_019e73c0",    "range": {      "from": "2019-08-24T14:15:22Z",      "to": "2019-08-24T14:15:22Z"    }  },  "data": [    {}  ]}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

Troubleshooting

Quick fixes for the things merchants most often get stuck on.

Discounts

Discount definitions (read-only inventory).