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
| Type | Input | Notes |
|---|---|---|
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 |
name | Two inputs | Submit as first_name + last_name |
address | Three inputs | Submit as address + city + postal_code |
Field names
| Field | name attribute |
|---|---|
email | |
| Company name | company_name |
| First name | first_name |
| Last name | last_name |
| Country | country_code (ISO 3166-1 alpha-2, e.g. DE) |
| VAT / Tax ID | vat_id |
| Phone | phone |
| Street address | address |
| City | city |
| Postal code | postal_code |
| Custom fields | Use 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
| Status | Body | Meaning |
|---|---|---|
| 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.
code | field | Meaning |
|---|---|---|
required | yes | A required field is empty |
too_long | yes | A value is longer than allowed |
invalid_email | yes | The email address is not valid |
invalid_country | yes | The country code is not a known ISO code |
invalid_selection | yes | A select value is not one of the field’s options |
missing_required | no | Required fields are missing (stores whose form was set up before field configuration existed) |
vat_country_required | no | A VAT / Tax ID was sent without a country |
vat_format | no | The VAT / Tax ID format is not valid for the country |
vat_unverified | no | The VAT / Tax ID could not be verified (only when live verification is required) |
form_disabled | no | The form is turned off in the app |
application_limit | no | The store is not accepting new applications |
missing_shop, method_not_allowed | no | The 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 %}