Skip to content
AM

Form submissions

Published Studio forms expose a public schema and submission route through the Commerce Storefront API.

Read the active schema

const schema = await commerce.forms.getSchema(formId);

This calls GET /storefront/v1/forms/{formId}/schema. The response includes the form ID, site ID, name, active version, target entity type, fields, and validation rules. The form must belong to the resolved active site or brand.

Submit data

const submission = await commerce.forms.submit(formId, {
  email: "alex@example.com",
  first_name: "Alex",
  referred_by: "Event",
});

The SDK sends:

POST /storefront/v1/forms/{formId}/submit
X-InBlack-SDK-Key: inb_pk_live_REDACTED
Content-Type: application/json


{
  "data": {
    "email": "alex@example.com",
    "first_name": "Alex",
    "referred_by": "Event"
  }
}

Public callers cannot supply contactId; the endpoint rejects it. The response returns the submission ID, site and form IDs, active form version, submitted data, optional resolved contact ID, and creation timestamp.

Validation

The handler requires a valid UUID form ID and a non-null data object. It enforces every field marked required; missing values, blank strings, and empty arrays fail with 400.

The current public handler does not apply the broader type/rule list suggested by old form drafts. Render inputs from the returned schema, but perform client-side format validation for user experience and treat the server response as authoritative.

Contact and custom-field mapping

crm_contact is the only supported target entity type for storefront submission mapping. If a form has field mappings, the service:

  1. Maps submitted field IDs to declared contact custom-field names.
  2. Validates mapped values against the active crm_contact schema.
  3. Requires an email, phone, or name identity field before accepting mapped custom fields.
  4. Resolves or creates the contact through the configured contact resolver.

Mappings for any other target_entity_type return 400. Submit custom values as the mapped top-level form fields; do not add a nested custom_fields object unless the form schema itself defines and maps that field.

Delivery behavior

After validation, the service commits the submission and publishes a commerce.storefront.form.submitted event to Studio. If a notification email is configured, it sends that notification after the commit. Notification failure does not roll back the accepted submission.

Abuse controls

Form routes use the general storefront limits: 100 requests per minute per IP and 100 per minute per SDK key. The request contract has no CAPTCHA or Turnstile token, no honeypot field, and no X-Idempotency-Key handling. Implement double-submit prevention in the client and add edge bot controls when needed.