Forms API

Lantern exposes form endpoints through Shopify’s App Proxy at /a/lantern. Use these endpoints to render dynamic forms on the storefront and submit responses that update customer data.

Get a form

Method: GET
Path: /a/lantern/form/{handle}
Path params: handle (string, required) — unique form handle

Returns the form structure so you can render inputs on the storefront.

{
  "id": "form-id-123",
  "handle": "newsletter-signup",
  "name": "Newsletter Signup",
  "fields": [
    {
      "handle": "profile:email",
      "label": "Email Address",
      "required": true,
      "valueType": "String",
      "fieldType": "Text",
      "inputType": "TextInput",
      "placeholder": "Enter your email"
    }
  ]
}

Form fields may include choices for select/radio inputs and propertyDefinition when the field maps to a Lantern property.

Submit a form

Method: POST
Path: /a/lantern/form/{handle}
Path params: handle (string, required)
Query params: locale (string, optional) — overrides the browser locale
Body: JSON object where keys are field handles and values are the submitted data

Example request body:

{
  "profile:first-name": "Alex",
  "profile:last-name": "Rivera",
  "profile:email": "[email protected]",
  "profile:birth-date": "1990-01-01",
  "attribute:favorite-color": "blue",
  "custom-field": "extra value"
}

Use profile: prefixes to update Shopify customer properties and attribute: prefixes for custom Lantern attributes. Other keys are stored as submitted.

Successful responses return the submitted data and an event id you can use for auditing:

{
  "success": true,
  "eventId": "evt_12345abcde",
  "data": {
    "profile:first-name": "Alex",
    "profile:email": "[email protected]"
  }
}

Errors

400 Bad Request for validation issues
401 Unauthorized if the Shopify App Proxy signature is missing or invalid
422 Unprocessable Entity for invalid submissions (for example, required fields missing)

Overview

Liquid API

Window API

REST API

Get a form

Submit a form

Errors

​Get a form

​Submit a form

​Errors

Get a form

Submit a form

Errors