The Form

The checkout form is driven by a single enhancer activated by data-next-checkout on a <form>. It finds your fields, validates them, populates the country and state dropdowns, manages a separate billing address, and submits the order.

How Fields Are Found

The SDK does not rely on input name or id. It locates each field by attribute:

• data-next-checkout-field="<name>" — current convention
• os-checkout-field="<name>" — legacy convention (still supported)

Both work; prefer data-next-checkout-field in new pages. The value is the standard field name, which the SDK maps to the order API for you.

Standard field names

Card field names are covered in Payment.

Validation

Validation runs on submit and on field blur. If a field is invalid, the SDK marks it and shows a message; on submit it focuses and scrolls to the first error.

When a field fails, the SDK adds the has-error / next-error-field classes to it and writes the message into an error container (see Error display). A valid field gets no-error.

Error display

The SDK writes each field's error message into a container it finds near the field. You can provide one explicitly:

<input data-next-checkout-field="email" type="email" />
<div data-next-error="email"></div>

os-checkout-error="email" is also accepted. If no container is found, the SDK creates an inline error label next to the field.

Country & State

The country dropdown is filled from the campaign's available shipping countries. The province dropdown is populated from the selected country's states. Changing the country:

• Refreshes the province options for that country
• Re-labels the state field (e.g. "State", "Province", "Region")
• Re-labels and re-validates the postal field (e.g. "ZIP", "Postcode")

You can leave both <select> elements empty in your HTML — the SDK fills them.

Progressive Address Fields

To keep the form visually short, the city / state / postal block can stay hidden until the visitor starts a street address. Wrap those fields in a location container:

<div data-next-component="location">
  <input  data-next-checkout-field="city" />
  <select data-next-checkout-field="province"></select>
  <input  data-next-checkout-field="postal" />
</div>

The container is hidden (next-location-hidden) until address1 receives a value, then revealed. The matching billing container is data-next-component="billing-location".

Separate Billing Address

By default the billing address equals the shipping address. To let customers enter a different one, add a billing toggle and a billing form container:

<!-- toggle: checked = same as shipping -->
<input type="checkbox" name="use_shipping_address" checked />

<!-- shown only when billing differs from shipping -->
<div data-next-component="billing-form">
  <input data-next-checkout-field="billing-fname" />
  <input data-next-checkout-field="billing-lname" />
  <input data-next-checkout-field="billing-address1" />
  <input data-next-checkout-field="billing-city" />
  <select data-next-checkout-field="billing-province"></select>
  <input data-next-checkout-field="billing-postal" />
  <select data-next-checkout-field="billing-country"></select>
</div>

Billing fields use the same standard names prefixed with billing-. When the toggle says billing is the same as shipping, the billing form is hidden and only shipping is validated. When it differs, the billing form expands and its fields are validated too.

Component Containers

These optional containers let the SDK manage sections of the form. Each accepts the data-next-component form (preferred) or the legacy os-checkout-component / os-checkout-element form.

Next Steps

• Card fields and payment methods: Payment
• Speed up address entry: Address Autocomplete
• All field names and attributes: Reference → Attributes
• State classes the form toggles: Reference → CSS