Custom Form Integration

Last updated: October 8, 2026

The app ships a B2B Registration Form block you add via the theme editor. If you need full control over markup and UX, you can build your own form instead and POST to the same endpoint.


Submission endpoint

POST /apps/b2b/register

Accepts application/x-www-form-urlencoded or multipart/form-data. Returns JSON.

/apps/b2b is the default app proxy path. If you changed the app’s proxy URL under Settings > Apps in your Shopify admin, use your prefix and subpath instead, for example /apps/wholesale/register. The app’s own block has an App proxy path setting for the same reason.


Reading the form config

The app publishes a PUBLIC_READ shop metafield (b2b_app.form_config) with the active field schema. Read it to know which fields are enabled and their configuration.

In Liquid:

{% assign cfg = shop.metafields.b2b_app.form_config.value %}

Via Storefront API:

const { data } = await fetch('/api/2024-01/graphql.json', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Shopify-Storefront-Access-Token': window.Shopify.storefrontAccessToken,
  },
  body: JSON.stringify({ query: `{
    shop {
      metafield(namespace: "b2b_app", key: "form_config") { value }
    }
  }` }),
}).then(r => r.json());

const cfg = JSON.parse(data.shop.metafield.value);

Field schema

Each object in cfg.fields:

{
  key: string;          // POST field name
  type: string;         // see field types below
  label: string;
  placeholder: string;
  required: boolean;
  options?: { value: string; label: string }[];   // select fields
  countries?: { code: string; name: string }[];   // country fields
  translations?: Record<string, { label?: string; placeholder?: string }>;
}

cfg.pendingTag holds the tag a customer gets while their application is waiting (default b2b-pending).

Translated labels

field.translations holds a label and placeholder per storefront language, keyed by lowercase language code (nl, de, pt-pt, de-at). It includes the translations you enter on the app’s Translations page and built-in translations for the standard fields. Use it the same way the app’s block does: try the full storefront language, then the base language, then the field’s own label.

{% assign b2b_lang = localization.language.iso_code | downcase %}
{% assign b2b_lang_base = b2b_lang | split: '-' | first %}

{% for field in cfg.fields %}
  {% liquid
    assign tr = field.translations[b2b_lang]
    if tr == blank
      assign tr = field.translations[b2b_lang_base]
    endif
    assign flabel = tr.label | default: field.label
    assign fplaceholder = tr.placeholder | default: field.placeholder
  %}
  ...
{% endfor %}

Loop over cfg.fields rather than hardcoding inputs. The metafield is rewritten every time you save the form fields in the app, so a looped form picks up added, removed, reordered and relabeled fields with no theme change.

Field types

TypeInputNotes
text<input type="text">
email<input type="email">
tel<input type="tel">
number<input type="number">
url<input type="url">
textarea<textarea>
select<select>Options in field.options
checkbox<input type="checkbox">Submitted as "on" when checked
country<select>Options in field.countries; submit the country code
vat<input type="text">Server validates format and optionally checks VIES
nameTwo inputsSubmit as first_name + last_name
addressThree inputsSubmit as address + city + postal_code

Field names

Fieldname attribute
Emailemail
Company namecompany_name
First namefirst_name
Last namelast_name
Countrycountry_code (ISO 3166-1 alpha-2, e.g. DE)
VAT / Tax IDvat_id
Phonephone
Street addressaddress
Citycity
Postal codepostal_code
Custom fieldsUse field.key from the metafield config

email is always required. Every other field is required only when its required flag is set in the config.


Handling the response

StatusBodyMeaning
200{ ok: true }Submitted. Also returned for duplicate submissions (idempotent).
400{ error, code, field? }A field is missing or invalid
403{ error, code: "form_disabled" }Form disabled in settings
422{ error, code }VAT / Tax ID check failed
429{ error, code: "application_limit" }The store is not accepting new applications

error is an English message. To show messages in the storefront’s language, translate by code and fall back to error for a code you don’t know. When one field is at fault, field is its key from cfg.fields, so you can put that field’s translated label into the message.

codefieldMeaning
requiredyesA required field is empty
too_longyesA value is longer than allowed
invalid_emailyesThe email address is not valid
invalid_countryyesThe country code is not a known ISO code
invalid_selectionyesA select value is not one of the field’s options
missing_requirednoRequired fields are missing (stores whose form was set up before field configuration existed)
vat_country_requirednoA VAT / Tax ID was sent without a country
vat_formatnoThe VAT / Tax ID format is not valid for the country
vat_unverifiednoThe VAT / Tax ID could not be verified (only when live verification is required)
form_disablednoThe form is turned off in the app
application_limitnoThe store is not accepting new applications
missing_shop, method_not_allowednoThe request did not come through the app proxy, or was not a POST

Codes never change meaning. New ones may be added, which is why the fallback to error matters.


Complete Liquid example

{% assign cfg = shop.metafields.b2b_app.form_config.value %}

{% if cfg == blank %}
  <p>Form not configured yet.</p>
{% elsif customer and customer.tags contains 'b2b-accepted' %}
  <p>You already have an active B2B account.</p>
{% elsif customer and customer.tags contains cfg.pendingTag %}
  <p>Your application is under review.</p>
{% else %}

{% assign b2b_lang = localization.language.iso_code | downcase %}
{% assign b2b_lang_base = b2b_lang | split: '-' | first %}

<div id="b2b-wrap">
  <div id="b2b-success" style="display:none">
    <p>Application received. We'll be in touch.</p>
  </div>

  <form id="b2b-form" novalidate>
    {% for field in cfg.fields %}
      {% liquid
        assign tr = field.translations[b2b_lang]
        if tr == blank
          assign tr = field.translations[b2b_lang_base]
        endif
        assign flabel = tr.label | default: field.label
        assign fplaceholder = tr.placeholder | default: field.placeholder
      %}
      {% if field.type == 'name' %}
        <label>First name
          <input type="text" name="first_name" {% if field.required %}required{% endif %}>
        </label>
        <label>Last name
          <input type="text" name="last_name" {% if field.required %}required{% endif %}>
        </label>

      {% elsif field.type == 'address' %}
        <label>{{ flabel }}
          <input type="text" name="address" {% if field.required %}required{% endif %}>
        </label>
        <label>City
          <input type="text" name="city" {% if field.required %}required{% endif %}>
        </label>
        <label>Postal code
          <input type="text" name="postal_code" {% if field.required %}required{% endif %}>
        </label>

      {% elsif field.type == 'country' %}
        <label>{{ flabel }}
          <select name="country_code" {% if field.required %}required{% endif %}>
            <option value=""></option>
            {% for c in field.countries %}
              <option value="{{ c.code }}">{{ c.name }}</option>
            {% endfor %}
          </select>
        </label>

      {% elsif field.type == 'select' %}
        <label>{{ flabel }}
          <select name="{{ field.key }}" {% if field.required %}required{% endif %}>
            <option value=""></option>
            {% for opt in field.options %}
              <option value="{{ opt.value }}">{{ opt.label }}</option>
            {% endfor %}
          </select>
        </label>

      {% elsif field.type == 'textarea' %}
        <label>{{ flabel }}
          <textarea name="{{ field.key }}" placeholder="{{ fplaceholder }}" {% if field.required %}required{% endif %}></textarea>
        </label>

      {% elsif field.type == 'checkbox' %}
        <label>
          <input type="checkbox" name="{{ field.key }}" {% if field.required %}required{% endif %}>
          {{ flabel }}
        </label>

      {% else %}
        <label>{{ flabel }}
          <input type="{{ field.type | replace: 'vat', 'text' }}" name="{{ field.key }}"
            placeholder="{{ fplaceholder }}" {% if field.required %}required{% endif %}>
        </label>
      {% endif %}
    {% endfor %}

    <p id="b2b-error" style="display:none; color:red;"></p>
    <button type="submit">Apply for wholesale access</button>
  </form>
</div>

<script>
(function () {
  var wrap = document.getElementById('b2b-wrap');
  var form = document.getElementById('b2b-form');
  var errorEl = document.getElementById('b2b-error');
  var successEl = document.getElementById('b2b-success');

  // Your own wording per code, in the storefront's language. {field} is
  // replaced with the field's label. Unknown codes fall back to data.error.
  var MESSAGES = {
    required: '{field} is required.',
    too_long: '{field} is too long.',
    invalid_email: 'Please enter a valid email address.',
    invalid_selection: 'Please choose a valid option for {field}.',
    vat_format: 'The VAT / Tax ID format is not valid for this country.',
    vat_country_required: 'Please choose a country for your VAT / Tax ID.'
  };
  var LABELS = {
    {%- for field in cfg.fields -%}
      {%- liquid
        assign tr = field.translations[b2b_lang]
        if tr == blank
          assign tr = field.translations[b2b_lang_base]
        endif
        assign flabel = tr.label | default: field.label
      -%}
      {{ field.key | json }}: {{ flabel | json }}{% unless forloop.last %},{% endunless %}
    {%- endfor -%}
  };

  function message(data) {
    var text = MESSAGES[data.code];
    if (text && text.indexOf('{field}') !== -1) {
      text = data.field && LABELS[data.field] ? text.replace('{field}', LABELS[data.field]) : null;
    }
    return text || data.error || 'Something went wrong.';
  }

  form.addEventListener('submit', async function (e) {
    e.preventDefault();
    errorEl.style.display = 'none';

    try {
      var res = await fetch('/apps/b2b/register', { method: 'POST', body: new FormData(form) });
      var data = await res.json();
      if (data.ok) {
        form.style.display = 'none';
        successEl.style.display = '';
      } else {
        errorEl.textContent = message(data);
        errorEl.style.display = '';
      }
    } catch (_) {
      errorEl.textContent = 'Network error. Please try again.';
      errorEl.style.display = '';
    }
  });
})();
</script>

{% endif %}