Forms

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

const form = await sdk.cms.form.create({
  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 },
  ],
});

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

Retrieve a form by ID or key.

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

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

List Forms

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

Update Form

await sdk.cms.form.update({
  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 },
  ],
});

Delete Form

Deletes the form and all its submissions.

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

Submit Form

Storefront submissions require a contact session for the same store. The storefront helper creates or reuses that session, loads the current form schema, and maps values to the server-owned field IDs and wire types:

await arky.cms.form.submitByKey({
  key: 'contact-form',
  values: {
    name: 'Jane Doe',
    email: 'jane@example.com',
    message: 'Hello, I have a question...',
  },
});

Unknown fields, missing required values, and values with the wrong schema type are rejected before the POST. Use the lower-level method only when you already have the current schema and need to provide exact fields yourself:

await arky.client.cms.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: 'jane@example.com' },
    { type: 'text', id: 'fld_message', key: 'message', value: 'Hello, I have a question...' },
  ],
});

Get Submissions

List submissions for a form (admin only).

const { items, cursor } = await sdk.cms.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);
});

Get Single Submission

const submission = await sdk.cms.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": "jane@example.com" },
    { "type": "text", "id": "fld_message", "key": "message", "value": "Hello!" }
  ],
  "created_at": 1704067200
}

Update Submission

Edit a collected submission (admin only).

await sdk.cms.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: 'jane@example.com' },
    { type: 'text', id: 'fld_message', key: 'message', value: 'Updated message' },
  ],
});

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 |