Integrations Guide

When an application is approved, B2B Onboard writes customer metafields to the Shopify customer record. These metafields are available to any app or Liquid template that reads customer data.

The custom namespace is the standard Shopify namespace that third-party apps can auto-discover. The b2b_onboard namespace contains app-specific internal fields.

Company metafields (written on approval)

When approval creates a new B2B Company, B2B Onboard also writes business fields onto the company record as metafields in the b2b_onboard namespace. These are readable by Shopify Flow, reports, and any app with company read access:

Fields with no submitted answer are left off rather than written blank, and approving an applicant into an existing company writes nothing — the b2b_onboard values on a company you already had are never overwritten (your own bound metafields follow the per-binding policy described below). In Liquid: {{ order.company.metafields.b2b_onboard.tax_id.value }}.

On every plan, each question on a form can be mapped to one or more of your existing metafield definitions on the Customer, Company or Company location. The applicant's answers are written to those fields when you approve the application.

Where the definitions come from

Definitions come from Settings → Custom data → Customers / Companies / Company locations in your Shopify admin. B2B Onboard lists the definitions of compatible types so you can pick one; it never creates, edits or deletes definitions on your behalf.

Which field types can be mapped

Address blocks, file uploads and layout elements (headings, paragraphs) cannot be mapped — they have no single value to store.

Choices

If you bind a dropdown or multi-select to a definition that has a fixed list of choices, the field's option values must match that list. The form editor warns you when they do not, so you can fix the options before applicants see them.

What happens to a value that already exists

Each binding has its own policy for records that already hold a value:

• Keep existing value (fill only when empty) — the default. The answer is written only where the field is currently empty.
• Overwrite existing value — the answer replaces whatever is stored.
• New records only — the answer is written only when the approval creates the customer, company or location.

Before you confirm an approval, the Approve page lists every planned write and marks the ones that would replace an existing value, showing the value being replaced. Overwrites follow the policy you chose on the binding; the page shows the value being replaced so you can cancel if it looks wrong.

When an answer can't be written

Shopify accepts a value only when it fits the definition you created: a number field needs a number, a date field needs a date, and a field with a fixed list of choices needs one of those choices. When a planned write would be rejected, the Approve page blocks the approval with a warning titled 1 metafield can't be written (3 metafields can't be written when several are affected). Each one is listed as the question, the key it maps to and the reason — for example Annual turnover → custom.turnover: "about 40k" is not a whole number. Approve Application stays disabled until you pick one of two ways forward:

• Edit application — the button in the warning opens the application for editing. Correct the answer, save, and the warning clears so you can approve as normal. This is the right choice when the answer is simply wrong or mistyped.
• I understand — approve without these 3 metafields — tick this checkbox to approve past the values instead (it reads I understand — approve without this metafield when only one is affected). Everything else — the customer, the tags, the company, the approval email — is created exactly as normal, and nothing at all is written for the skipped keys.

An override is recorded so the missing values stay explainable later: the application timeline gets Approved without 1 metafield: CUSTOMER:custom.turnover (Approved without 3 metafields: <keys> when several were skipped), and the same entry goes to the audit log. Only the metafield keys are recorded — never the answers themselves.

The checks run against your own definitions, read live from Shopify each time the Approve page is opened, so a validation you edited a minute earlier applies straight away. Besides the type, B2B Onboard checks the validations you set on the definition: the list of choices, a minimum or maximum length (text) or value (numbers), the number of decimal places, a date range, the domains a link is allowed to point at, and the minimum or maximum size of a list. A regular-expression pattern is checked too, but only when it is safe to run against applicant-supplied text — a pattern that could be slow to evaluate is skipped rather than allowed to hold up an approval, and Shopify still applies it at write time.

Some rejections can only appear at write time, because Shopify has the last word. The approval itself still completes: the customer and company are created, and only those values are missing. The application then shows up under Action required as 2 metafields not written, and its drawer (Metafields could not be written) names each key with the reason Shopify gave, with Open application to go and deal with it. On the application, fix the answer if it was wrong and use Retry metafield writes — only the keys that failed are written again, and the row leaves Action required once they all succeed.

After approval

The application page shows a Shopify metafields card listing each key as written, overwritten (with the previous value) or failed (with the reason Shopify gave). Keys you approved past are listed separately under Skipped by you on approval, so a value that was never attempted is never mistaken for one that failed — the card appears even when every key was skipped and nothing was written. The company page shows the current values read live from Shopify, next to the fixed fields described above.

Data erasure

When Shopify sends a customers/redact request for an applicant, B2B Onboard deletes the values it wrote and restores the values it overwrote to what they held before the approval.

The fixed b2b_onboard fields listed in the previous section keep working exactly as before, alongside any bindings you add.

From your Shopify metafields

The form editor's field palette also works the other way round: it lists your compatible definitions that no question maps to yet, and adding one inserts a ready-made question already mapped to it. The four customer fields the app creates itself for invoicing apps (custom.company_name, custom.contact_name, custom.vat_number, custom.tax_id) are not suggested there because approval already fills them (custom.vat_number unless the answer is known not to be a VAT number — for example a US, Canadian, Australian or New Zealand buyer — while custom.tax_id holds the tax answer whenever the form asks for a tax ID), and for the same reason they are left out of a field's Write to metafield list. For a definition with a fixed list of choices, the new dropdown's options are taken from that list.

Sufio is a popular invoicing app for Shopify that generates professional invoices automatically.

How it works: Sufio auto-reads custom.vat_number from the customer record and includes it on invoices. No additional configuration is needed in Sufio. B2B Onboard fills custom.vat_number with the applicant’s tax answer unless it is known not to be a VAT number (a buyer in the US, Canada, Australia or New Zealand, an ABN, NZBN or Canadian business number, or a Norwegian organisation that is not VAT-registered), so a US EIN or an Australian ABN is not printed as a VAT number; custom.tax_id holds the tax answer whenever the form asks for a tax ID.

If you use Shopify B2B: Sufio also reads the native taxRegistrationId from B2B Company locations. If you have B2B Company Creation enabled in B2B Onboard settings, the tax registration ID is written there too.

Setup: No setup required. Approve an application in B2B Onboard, and the VAT number will appear on the next Sufio invoice for that customer.

Order Printer is Shopify's free app for printing invoices, packing slips, and receipts using Liquid templates.

Best approach — native B2B objects: If you use Shopify B2B Company Creation, the most reliable method is to use native B2B Liquid objects in your Order Printer template:

{% if order.company %}
  <p><strong>Company:</strong> {{ order.company.name }}</p>
{% endif %}
{% if order.company_location.tax_registration_id %}
  <p><strong>VAT:</strong> {{ order.company_location.tax_registration_id }}</p>
{% endif %}

Alternative — customer metafields: If you do not use B2B Company Creation, you can access customer metafields directly:

{% if customer.metafields.custom.company_name %}
  <p><strong>Company:</strong> {{ customer.metafields.custom.company_name.value }}</p>
{% endif %}
{% if customer.metafields.custom.vat_number %}
  <p><strong>VAT:</strong> {{ customer.metafields.custom.vat_number.value }}</p>
{% endif %}

custom.vat_number is not set for a buyer in the US, Canada, Australia or New Zealand, for an ABN, NZBN or Canadian business number, or for a Norwegian organisation that is not VAT-registered, so the VAT line above is skipped for those buyers. To print every buyer’s tax number, use custom.tax_id, which holds the tax answer whenever the form asks for a tax ID.

Note: Customer metafield access in Order Printer templates can be unreliable due to a known Shopify limitation. The native B2B objects are the recommended approach.

Billbee is a German multi-channel order management and invoicing platform.

Limitation: Billbee only reads order-level note_attributes, not customer metafields. This cannot be solved directly in B2B Onboard.

Workaround with Shopify Flow: Create a Flow workflow that copies the customer VAT metafield to the order's note attributes when an order is created:

1. In Shopify admin, go to Settings → Flow
2. Create a new workflow with trigger: Order created
3. Add a condition: customer has metafield custom.vat_number (not set for buyers in the US, Canada, Australia or New Zealand, or for an ABN, NZBN or Canadian business number; use custom.tax_id, which holds the tax answer whenever the form asks for a tax ID, if you want every buyer’s tax number)
4. Add action: Update order note to include the VAT number with key vat-id
5. Turn on the workflow

Billbee will then pick up the vat-id from the order note attributes and use it in invoices.

For the best invoicing app compatibility, enable B2B Company Creation in your B2B Onboard settings. This works on any paid Shopify plan with B2B enabled — Shopify Plus or Shopify’s foundational B2B on non-Plus plans.

When B2B Company Creation is active, approving an application also:

• Creates a Shopify B2B Company with the company name and address
• Sets the taxRegistrationId on the company location (VAT number)
• Assigns the customer as a company contact
• Optionally assigns a B2B catalog (Shopify Plus) or adds the company's location to your Default B2B market (Basic, Grow, Advanced) for wholesale pricing

Invoicing apps that support Shopify's native B2B objects (including Sufio and Order Printer) will automatically pick up company names and tax registration IDs from orders placed by B2B customers.

See the B2B Company Creation settings for configuration details.

Any Shopify app or integration that reads customer metafields can access B2B Onboard data. The metafields use the standard custom namespace, which is discoverable through Shopify's metafield definitions API.

For developers: Query customer metafields via the Shopify Admin API:

{
  customer(id: "gid://shopify/Customer/123") {
    metafields(first: 10, namespace: "custom") {
      edges {
        node {
          key
          value
        }
      }
    }
  }
}

For Liquid themes: Access metafields in your theme templates:

{{ customer.metafields.custom.company_name.value }}
{{ customer.metafields.custom.vat_number.value }}
{{ customer.metafields.custom.tax_id.value }}

custom.vat_number holds the tax answer unless it is known not to be a VAT number (a buyer in the US, Canada, Australia or New Zealand, an ABN, NZBN or Canadian business number, or a Norwegian organisation that is not VAT-registered); custom.tax_id holds the tax answer whenever the form asks for a tax ID.

If you use an invoicing app not listed on this page and need help connecting it to B2B Onboard, contact support.

Connect your own Google Maps JavaScript API key to enable Google-powered address autocomplete on the address fields of your public registration form. When a buyer starts typing a street address, Google suggests matching addresses; picking a suggestion automatically fills the street address, city, state / province, country, and ZIP / postal code. This improves data quality and speeds up applications.

The key is a public, HTTP-referrer-restricted browser key that you own and are billed for directly by Google. Mentilead does not proxy, meter, or bill for Maps usage. Google offers a generous free monthly allowance for autocomplete; see Google's pricing for details. Leave the field blank to keep autocomplete off — buyers then enter addresses manually, exactly as before.

Setup:

1. In the Google Cloud Console, create (or select) a project and enable both the Maps JavaScript API and the Places API.
2. Under APIs & Services → Credentials, create an API key.
3. Add an HTTP referrer restriction for your storefront domain (for example https://your-store.myshopify.com/* and any custom domain) so the key can only be used from your storefront.
4. Copy the key and paste it into Settings → Integrations → Address autocomplete in B2B Onboard, then click Save.

Because the key is restricted to your storefront domain, it is safe for the browser to load it — that is how Google's Maps JavaScript API is designed to work. To disable autocomplete later, clear the field and save.