> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lantern.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Forms API

> Retrieve and submit Lantern forms through the Shopify app proxy.

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.

```json theme={null}
{
  "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:

```json theme={null}
{
  "profile:first-name": "Alex",
  "profile:last-name": "Rivera",
  "profile:email": "alex@example.com",
  "profile:birth-date": "1990-01-01",
  "attribute:favorite-color": "blue",
  "custom-field": "extra value"
}
```

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

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

```json theme={null}
{
  "success": true,
  "eventId": "evt_12345abcde",
  "data": {
    "profile:first-name": "Alex",
    "profile:email": "alex@example.com"
  }
}
```

## 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)