Merchants build forms in the admin. For the screen-by-screen steps, see
Forms in the Help Center. This guide covers the model
and the API.
The model
Which carts get a form
Forms apply only to enrollment carts. A cart becomes one when the shopper adds an enrollment pack, or when it’s flagged with Flag a cart as enrollment eligible. A regular cart never gets a form. An enrollment cart gets every form that is Post Purchase, Active, and set to the cart’s country. Forms aren’t attached to enrollment packs, member types or products, so every enrollment in a country gets the same fields. When more than one form matches, checkout shows their fields together as one form.When the form appears
1
Checkout places the order
The shopper pays. Checkout captures the payment and places the order. Outstanding form fields never block this step.
2
The order confirmation page shows the form
Fluid-hosted checkout renders the form at the top of the order confirmation page, above the order-details drop zones. It appears only when the order has an enrollment and the enrollment has outstanding Post Purchase fields.
3
The shopper submits
Checkout saves each answer. File fields upload as soon as a file is dropped in.
4
The enrollment completes
When every required field has an answer, the enrollment is complete. Fluid saves a copy of the answers with the new member’s record and sends the enrollment completed webhook.
What the order and the form each decide
The order decides the purchase and the membership. The shopper is charged, the order exists, and the shopper is enrolled as a member of the enrollment’s member type as soon as checkout places the order, whether or not they ever open the form. The form decides only whether the enrollment is complete. An incomplete enrollment means:- The form keeps appearing on the order confirmation page, with saved answers filled in.
- Fluid emails up to five reminders over about 25 days, each linking back to that page, while the company’s enrollment completion reminder email is active.
- The enrollment completed webhook hasn’t fired yet.
Read and answer the form through the API
Fluid-hosted checkout does all of this for you. Use these steps when you build your own order confirmation experience on the Checkout API, or when an agent or back-office tool collects the answers instead.1
Get the enrollment token
Complete checkout returns the new order. On an enrollment order, its
enrollment_token addresses the enrollment. You can read it again later from Show order. On a regular order, it’s null.2
Read the fields
Call Show enrollment with the token. It needs no Bearer token: the enrollment token is the credential, so treat it like a password. The response lists
enrollment_fields, each with its type, order, placement, any saved answer, and its builder settings, plus the enrollment’s state.Render only fields whose placement is post_purchase. That’s what Fluid-hosted checkout shows. The list can also carry fields from other active forms for the country.3
Save each answer
Send each answer with Submit enrollment field answer. The answer is a string, so send a date as
1985-04-12 and a yes-or-no answer as text.For a file field, send the file with Upload file for enrollment field. Fluid accepts JPEG, PNG, WebP, TIFF or PDF files up to 5 MB.4
Change a saved answer
Use Update enrollment field answer with the field’s
id in the path, the same ID you submitted the answer with. It changes the field’s latest saved answer. A field with no saved answer yet returns 404, so submit its first answer instead. Submitting a second answer for the same field creates another answer instead of replacing the first.5
Check completion
Read Show enrollment again. When
state is complete, the enrollment is finished. After that, every write to the enrollment is refused with 422.Webhooks
Subscribe to these with the Webhooks guide. Call List webhook resources for the exact resource and event pairs your company can use.
To act on finished enrollments, such as sending a welcome kit or syncing to a compensation system, use
enrollment_completed. Don’t use form_submitted for that.
Managing forms
Build and edit forms, and read or export all of a form’s responses, in the admin. See Forms. You can also manage forms through the API, as Build a form through the API shows. Through the Checkout API you can read and answer one enrollment’s fields at a time, by its token.Build a form through the API
Use the Forms API when a script or an agent sets up forms, for example while you open a country. Every request takes a company Bearer token. Reading needs the forms view permission, and writing needs the forms update permission. The steps below build Dunder Mifflin’s form for Germany. Each operation’s reference page holds its full parameters and responses.Find the country’s ID
A form’scountry_ids takes Fluid’s ID for each country. Read it from List company countries: use the entry’s country.id, not the entry’s own id, which identifies your company’s settings for the country.
74, Germany’s ID. A country you haven’t opened isn’t in that list. Find it in List countries, which returns Fluid’s whole country catalog.
Write the fields
Each field is a component: an object with anelement_type and its settings. List form elements describes every element type. Dunder Mifflin saves the German fields in enrollment-germany.json:
enrollment-germany.json
- Set
is_form_fieldtotrueon every component that collects an answer. Without it, the element isn’t an enrollment field: checkout doesn’t ask for it, and it never holds an enrollment open. - An identity field is an
inputwhosepuck_typenames it, such aslegal_name,emailordate_of_birth. - Use
short_text_entryfor a tax ID outside the United States. Checkout formats thessnidentity field as a US Social Security number. - Fields appear in the order you list them.
Create the form as a draft
form_components is a JSON-encoded string, not an array. Let jq encode the file into the request body:
jq writes, the components are one escaped string:
create-form.json
- Send the fields inside the
formobject. The API reads nothing outside it. - Set
form_typetopost_purchasefor a form checkout shows.generalmakes a standalone form.pre_purchaseis retired and returns422. - A new form is a
draftunless you setstatus, so no enrollee sees it while you check it. - Marking a field
sensitive_infoneeds the forms manage-sensitive permission. Without it, the request returns422and creates nothing. - The
Idempotency-Keyheader makes a retry safe. The same request with the same key returns the form the first request created.
id, here 5821. Its form_components carry each element’s id. Save the response as form.json; you need those IDs to change the fields later.
Activate it
Send only what changes. A request withoutform_components leaves the fields as they are.
One form per country, or one form for several
Checkout shows every active Post Purchase form for the cart’s country, combined into one form. Overlapping forms all show. Use this rule of thumb:- Shared fields: one form across countries. Questions every market asks the same way can live on one form whose
country_idslists each country. - Country-specific legal or tax fields: one form per country. A German tax number on a form shared with the United States would ask American enrollees for it too.
- Ask each question once. If a shared form and a country’s own form both ask how the enrollee heard about you, enrollees in that country see the question twice. The same goes for Fluid’s generic enrollment form for a country, which opening the country can add. See Open a country.
country_ids replaces the form’s countries. Read the current ones from the form’s countries. Dunder Mifflin’s Rep preferences form asks for product interests and a contact preference in the United States (214) and Canada (35). This adds Germany:
Change fields without dropping any
form_components in an update is the form’s whole new layout:
- A component with the
idof one of the form’s elements updates that element in place, and its answers stay with it. - A component without an
idadds a new element. - An element you leave out is deactivated. Its answers are kept, but checkout stops asking for it.
form_components, which carry their IDs. Every create and update response returns them, and so does List forms. Don’t rebuild them from List form elements: it also lists elements that earlier edits deactivated.
This adds a date of birth to the German form and keeps every existing field:
Follow up on responses
- List form respondents returns each submission with its answers. Sensitive answers read
********unless your token holds the forms view-sensitive permission. - List incomplete enrollees lists who still owes this form, and whether a reminder would go to them now.
- Send manual enrollment reminders emails the eligible ones. Send
enrollment_idsto remind only some. Each enrollee gets at most one manual reminder per 24 hours, counting automatic reminders. - Export form responses as CSV returns a download URL.
include_sensitive=trueunmasks sensitive answers only for a token with the forms view-sensitive permission.
404. Both return 422 for a form that isn’t Post Purchase.
Example: a rep enrollment form for the United States
Dunder Mifflin enrolls paper sales reps in the United States. It needs each new rep’s legal name, date of birth and a signed W-9 to pay commissions.
The form is
Enrollment - United States, with Form type set to Post Purchase, Countries set to United States, and Active on.
When Pam Beesly buys the Paper Sales Starter Kit from Dwight Schrute’s link:
- She pays on one page with no extra fields. Her order is placed, Dwight gets credit for it, and Pam becomes a member of the enrollment pack’s member type.
- The order confirmation page asks for her legal name, date of birth and signed W-9, and the optional survey question.
- She uploads her W-9 the next day from the reminder email’s link. The enrollment completes, and the enrollment completed webhook tells the company’s compensation system to start paying her commissions.
Enrollment - Canada, set to Canada only. It asks for a SIN in a Short Text Entry field, with Sensitive Info on, instead of the W-9.
Do it through the API: Build a form through the API creates the German form with the same requests. For these forms, change the title, the country’s ID and the components.
Example: “How did you hear about us?”
To learn where new members come from, add one optional Multiple Choice field to each country’s Post Purchase form:- Label: How did you hear about us?
- Options: Social media, A friend or family member, A rep, Search, An event, Other
- Required: off, so the question never holds an enrollment open
Recommended field sets
Enrollment
For terms and policies the shopper must accept before buying, use Agreements, not a form field. Agreements linked to an enrollment appear in checkout before the order is placed, and each acceptance is recorded.
Attribution and preferences
Gotchas
- Forms are country-scoped, not pack-scoped. You can’t show a different form for each enrollment pack or member type. Use one form per country when countries need different fields.
- A form must be Active and Post Purchase. A draft, or a General form, never appears at checkout.
- General forms can hold enrollments open. Completion counts the fields of every active form for the cart’s country, but checkout shows only Post Purchase fields. Keep General forms out of the countries where you enroll members, or turn them off when you don’t need them.
- Pre Purchase forms are retired. An older form with that type still asks before payment. Change it to Post Purchase.
- A sponsor field doesn’t set a sponsor. Answers are stored as text. They don’t change who gets credit for the order or the new member’s sponsor.
- No conditional logic and no pattern checks. Every field shows to every shopper who gets the form.
Related pages
Forms in the admin
Build forms, set their countries, and view, export and follow up on responses.
Checkout
How Fluid Checkout works and how to extend it.
Headless commerce
Run the cart-to-order flow on the Checkout API.
Webhooks
Subscribe to enrollment and form events.