Forms

Create forms and collect submissions

Forms allow you to create structured data collection endpoints. Define form fields as a typed schema, then collect submissions from your users. Submissions can trigger workflows (e.g. send a notification email on contact form submission).

Create Form

POST /v1/stores/{storeId}/forms

SDK: sdk.form.createForm()

const form = await sdk.form.createForm({
  key: 'contact',
  schema: [
    { type: 'text', id: 'fld_name', key: 'name', required: true },
    { type: 'text', id: 'fld_email', key: 'email', required: true },
    { type: 'text', id: 'fld_message', key: 'message', required: true },
  ],
});

Parameters

Name	Type	Description
`key` required	`string`	Unique form identifier
`schema` optional	`FormSchema[]`	Typed form field definitions

Schema Field Types

Type	Extra options
`text`	`required`
`number`	`required`, `min`, `max`
`boolean`	`required`
`date`	`required`
`geo_location`	`required`
`select`	`required`, `options: string[]`

Response

{
  "id": "form_abc123",
  "key": "contact",
  "store_id": "store_123",
  "schema": [
    { "type": "text", "id": "fld_name", "key": "name", "required": true },
    { "type": "text", "id": "fld_email", "key": "email", "required": true },
    { "type": "text", "id": "fld_message", "key": "message", "required": true }
  ],
  "status": "active",
  "created_at": 1704067200,
  "updated_at": 1704067200
}

Get Form

GET /v1/stores/{storeId}/forms/{id}

SDK: sdk.form.getForm()

Retrieve a form by ID or key.

// By ID
const form = await sdk.form.getForm({ id: 'form_abc123' });

// By key
const form = await sdk.form.getForm({ key: 'contact' });

List Forms

GET /v1/stores/{storeId}/forms

SDK: sdk.form.getForms()

const { items, cursor } = await sdk.form.getForms({
  status: 'active',
  limit: 20,
});

Parameters

Name	Type	Description
`query` optional	`string`	Search in form keys
`key` optional	`string`	Filter by exact key
`status` optional	`string`	Filter by status
`ids` optional	`string[]`	Filter by specific form IDs
`limit` optional	`number`	Items per page
`cursor` optional	`string`	Pagination cursor
`sort_field` optional	`string`	Sort field
`sort_direction` optional	`asc \| desc`	Sort direction
`created_at_from` optional	`number`	Filter by creation date (start)
`created_at_to` optional	`number`	Filter by creation date (end)

Update Form

PUT /v1/stores/{storeId}/forms/{id}

SDK: sdk.form.updateForm()

await sdk.form.updateForm({
  id: 'form_abc123',
  schema: [
    { type: 'text', id: 'fld_name', key: 'name', required: true },
    { type: 'text', id: 'fld_email', key: 'email', required: true },
    { type: 'text', id: 'fld_phone', key: 'phone', required: false },
    { type: 'text', id: 'fld_message', key: 'message', required: true },
  ],
});

Parameters

Name	Type	Description
`id` required	`string`	Form ID
`key` optional	`string`	Updated key
`schema` optional	`FormSchema[]`	Updated form field schema
`status` optional	`ACTIVE \| ARCHIVED`	Updated status

Delete Form

DELETE /v1/stores/{storeId}/forms/{id}

SDK: sdk.form.deleteForm()

Deletes the form and all its submissions.

await sdk.form.deleteForm({ id: 'form_abc123' });

Submit Form

POST /v1/stores/{storeId}/forms/{formId}/submissions

SDK: sdk.form.submit()

Submit data to a form. This endpoint is public and is typically called from your frontend by end users.

await sdk.form.submit({
  form_id: 'form_abc123',
  fields: [
    { type: 'text', id: 'fld_name', key: 'name', value: 'Jane Doe' },
    { type: 'text', id: 'fld_email', key: 'email', value: '[email protected]' },
    { type: 'text', id: 'fld_message', key: 'message', value: 'Hello, I have a question...' },
  ],
});

Parameters

Name	Type	Description
`form_id` required	`string`	Form ID to submit to
`fields` required	`FormField[]`	Submitted field values (must match the form schema)

Get Submissions

GET /v1/stores/{storeId}/forms/{formId}/submissions

SDK: sdk.form.getSubmissions()

List submissions for a form (admin only).

const { items, cursor } = await sdk.form.getSubmissions({
  form_id: 'form_abc123',
  limit: 50,
});

items.forEach(submission => {
  const name = submission.fields.find(f => f.key === 'name')?.value;
  console.log(submission.id, name, submission.created_at);
});

Parameters

Name	Type	Description
`form_id` required	`string`	Form ID
`query` optional	`string`	Search within submissions
`limit` optional	`number`	Items per page
`cursor` optional	`string`	Pagination cursor
`sort_field` optional	`string`	Sort field
`sort_direction` optional	`asc \| desc`	Sort direction
`created_at_from` optional	`number`	Filter by creation date (start)
`created_at_to` optional	`number`	Filter by creation date (end)

Get Single Submission

GET /v1/stores/{storeId}/forms/{formId}/submissions/{id}

SDK: sdk.form.getSubmission()

const submission = await sdk.form.getSubmission({
  form_id: 'form_abc123',
  id: 'sub_xyz789',
});

Submission Response

{
  "id": "sub_xyz789",
  "form_id": "form_abc123",
  "store_id": "store_123",
  "fields": [
    { "type": "text", "id": "fld_name", "key": "name", "value": "Jane Doe" },
    { "type": "text", "id": "fld_email", "key": "email", "value": "[email protected]" },
    { "type": "text", "id": "fld_message", "key": "message", "value": "Hello!" }
  ],
  "created_at": 1704067200
}

Update Submission

PUT /v1/stores/{storeId}/forms/{formId}/submissions/{id}

SDK: sdk.form.updateSubmission()

Edit a previously collected submission (admin only).

await sdk.form.updateSubmission({
  form_id: 'form_abc123',
  id: 'sub_xyz789',
  fields: [
    { type: 'text', id: 'fld_name', key: 'name', value: 'Jane D.' },
    { type: 'text', id: 'fld_email', key: 'email', value: '[email protected]' },
    { type: 'text', id: 'fld_message', key: 'message', value: 'Updated message' },
  ],
});

Parameters

Name	Type	Description
`form_id` required	`string`	Form ID
`id` required	`string`	Submission ID
`fields` required	`FormField[]`	Updated field values

Default Forms

Every new store is created with 3 default forms:

Key	Purpose
`contact`	Contact form
`service-intake`	Service intake form
`order-notes`	Order notes form