RECIPE: Update a Wix Form

Change what a form collects — add a field, relabel one, tighten a rule, reorder, retire one — on a form that already exists. Composing the field itself is in Create Form STEP 1: § Field types gives the common kinds' identifier / inputType / componentType and blocks, with copyable choice and checkbox fields, and § Silent breakers apply to an added field exactly as to a created one.

A PATCH, never a delete-and-recreate. An update keeps the formId everything downstream already holds — a frontend binding, an automation, a saved dashboard view — and spends no slot against the site's form cap.

The call

The calls in this recipe are complete as written: send them as they are, with no docs or schema lookup. Read the form, send the PATCH, and run the two read-backs in § Verify, in that order.

Each call's method page and the response fields the next step reads are below. Cite these pages as the calls' docs sources; none needs a search. A new field's shape is in Create Form STEP 1.

No formId yet ("my contact form")? List the forms and pick it by name: GET https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form&fieldsets=METADATA returns only names and IDs. That call skips disabled forms; if the form isn't there, call again with &enabled=false.

• ⚠️ namespace is a REQUIRED query parameter on the read, and this is what a revise run trips over. Without it the read returns 400 namespace has size 0, expected 10 or more, namespace must not be empty — a violation naming a field, so it reads like a body problem. Fix the call, don't reshape the payload. (The filter on POST .../v4/forms/query needs it too.)
• The read-back is the body. Apply your change to what the GET returned and send that as form. namespace is immutable and travels along; there is no fieldMask, and no revision outside form — inventing either is a silent partial write.
• ⚠️ Delete the legacy fields array before you send. The read-back carries fields (the old field list) next to formFields. Send both and the old list wins: the PATCH returns 200 and bumps revision, but a field you added only to formFields is dropped, and only its layout item is kept. Spreading the whole form ({ ...form, formFields }) does exactly this. Remove fields and deletedFields first: const { fields, deletedFields, ...body } = form.
• ⚠️ Append to formFields; never rebuild the entries you read. [...form.formFields, newField] works. Mapping the array to "clean up" each field — dropping fieldType, re-shaping an options block — fails with fieldType cannot be provided with any these fields: input_options, display_options on every field at once. The read-back's field objects are already a valid write shape: pass them through untouched and touch only the one field you are changing.
• formFields is replaced wholesale. Wix: "Any field that's missing from the array you send is moved to deletedFormFields, so resend every field you want to keep." Same for steps[].layout — miss an item and that field goes unplaced, which renders empty. Drops are recoverable from deletedFormFields, but nothing announces them.
• A stale revision is rejected — re-GET and re-apply; never guess or increment it.
• Plan caps apply to an added field. Field count reached its limit of N on a PATCH is the site's premium cap: reduce or upgrade, with the choice put to the user (Create Form § Plan caps). Never split the form across schemas to dodge it.

Adding a field

Build the new field from Create Form STEP 1: § Field types gives the identifier / inputType / componentType triple and the two block names — take all three from one row, and note that a dropdown or radio is inputType: "STRING". § Choice fields has a complete dropdown and multi choice to copy, and § Checkboxes has the agreement and email-subscription checkboxes. Composing a field from memory is what turns one PATCH into eight.

The field added most often is a newsletter or marketing-consent checkbox. It is a CONTACTS_SUBSCRIBE field, kept optional; a ticked box subscribes the submitter's email. For a box the visitor must tick to agree to terms, use "identifier": "CHECKBOX" with "required": true and no pii or contactMapping. The field below is complete; you do not need another page for it. The label is rich content, and validation sits in booleanOptions. For "at the end", give its layout item the row of SUBMIT_BUTTON and move the button one row down — never below the button:

Then four things are yours to generate:

• id — a fresh lowercase GUID (uuidgen | tr 'A-Z' 'a-z'), unique in the form.
• target — the immutable submission key, unique across the form: snake_case plus a short random suffix (job_industry_7f2b). A duplicate target is accepted and silently stores nothing for every field but one.
• one GUID per choice option — options[] each need their own, exactly like the field's; a readable slug is rejected (Create Form § Choice fields). Generate them with uuidgen, never by hand.
• the choices, declared twice — every option needs id + value + label, and validation.enum must list every one of those values. An empty validation is a free-text field, not a dropdown; the general "always include validation, even as {}" rule does not apply here, and getting it wrong is accepted with a 200.
• the layout item — add it to steps[<n>].layout.large.items, mirroring into medium / small if the form has them. For "at the end", give it the row of SUBMIT_BUTTON and move the button one row down, so the field is not placed below the button:

A field missing from the layout isn't dropped, but it sorts last and has no defined position in the owner's builder. To place it mid-form, insert at that row and bump every item at or after it — row restarts at 0 in each step.

A choice field's identifier is its kind — DROPDOWN, RADIO_GROUP, CHECKBOX_GROUP, TAGS — never TEXT_INPUT, which is accepted and stored as a plain text input (Create Form § Choice fields).

The other changes

Verify — an update regresses a form exactly as a create can

A 200 on the PATCH proves the body parsed, nothing about what was stored. Right after the PATCH, in the same run, send both of these reads. They are complete as written and need no lookup. Neither one alone is enough: the first shows the stored fields, deletedFormFields and layout; the second shows what the owner's dashboard renders.

Assert on these two read-backs, not on the PATCH response:

• the changed field is there, carrying the identifier and componentType you sent — a choice field with a non-empty options[], which is where a dropdown that degraded to a text input shows up;
• every field you meant to keep is still present, and every inputOptions.required still reads back as sent;
• a removed field is in deletedFormFields and has no layout item, and an added one has a layout item in the place you meant;
• the summary's formSummary.fields holds one entry with deleted: false per input field. A removed field stays there with deleted: true, so do not count it.

These two reads are the whole verification; do not add more.

Then hand back the dashboard links (Forms Dashboard Navigation): the form builder at wix-forms/form/{formId}, and that form's submissions at wix-forms/form/{formId}/submissions. New submissions carry the new field; past ones don't.

Troubleshooting

Related Documentation

• Read Forms and Submissions — finding the form to update when you have no formId yet
• Create Form — composing fields, the identifier table, choice fields, the layout rules, plan caps
• Forms Dashboard Navigation — the builder and submissions links to hand back
• Update Form — the PATCH contract and its replace semantics
• Form object — revision, hidden, deletedFormFields, steps[].layout
• About Form Fields — the premium and app fields' extra blocks, and every field-level rule