Skip to main content
A checkout form collects extra information from a shopper who is enrolling, such as a date of birth, a tax ID or a signed document. Fluid shows it after the payment is taken and the order is placed, so it never adds a step between the shopper and paying. This guide explains the model end to end, then shows how a custom checkout reads and answers the form through the Checkout API.
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.
Only fields marked Required keep an enrollment open. A form whose fields are all optional doesn’t.

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.
Checkout checks only that required fields are filled in. Fluid saves any string as an answer, so validate formats, such as a tax ID’s length, in your own front end before you submit.

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’s country_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.
This prints 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 an element_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_field to true on 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 input whose puck_type names it, such as legal_name, email or date_of_birth.
  • Use short_text_entry for a tax ID outside the United States. Checkout formats the ssn identity 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:
In the body jq writes, the components are one escaped string:
create-form.json
  • Send the fields inside the form object. The API reads nothing outside it.
  • Set form_type to post_purchase for a form checkout shows. general makes a standalone form. pre_purchase is retired and returns 422.
  • A new form is a draft unless you set status, so no enrollee sees it while you check it.
  • Marking a field sensitive_info needs the forms manage-sensitive permission. Without it, the request returns 422 and creates nothing.
  • The Idempotency-Key header makes a retry safe. The same request with the same key returns the form the first request created.
The response returns the form with its 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 without form_components leaves the fields as they are.
Enrollment checkouts in Germany now show the form after payment.

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_ids lists 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.
To add a country to an existing form, send the whole list, because 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 id of one of the form’s elements updates that element in place, and its answers stay with it.
  • A component without an id adds a new element.
  • An element you leave out is deactivated. Its answers are kept, but checkout stops asking for it.
Start from the form’s current 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:
Never send only the new field. Every component you leave out is deactivated, so the form would ask for nothing else. Sending an existing sensitive field without its id also counts as marking a new field sensitive, which needs the forms manage-sensitive permission.

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_ids to 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=true unmasks sensitive answers only for a token with the forms view-sensitive permission.
Manual reminders are turned on per company. Without them, both reminder operations return 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:
  1. 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.
  2. The order confirmation page asks for her legal name, date of birth and signed W-9, and the optional survey question.
  3. 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.
For Canada, Dunder Mifflin adds a second Post Purchase form, 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
Read the answers in the form’s responses in the admin, or export them as CSV. Do it through the API: the question is the last component in Write the fields. To add it to a form that’s already live, follow Change fields without dropping any. A Post Purchase form reaches new members only, because regular checkouts never show forms. To survey every customer, use a General form and share its link, for example in a post-purchase email.

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.

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.