Executive summary
- What: Shopify has confirmed that family_name is optional inside shipping_address and billing_address on Payments Apps API session requests for B2B orders.
- Why: B2B checkout has never required a buyer surname, so any payment app that validated the field as mandatory was rejecting legitimate wholesale sessions.
- Who: Teams that build or maintain a payments app handling B2B checkout, and Plus merchants who run a regional or custom payment provider alongside Shopify B2B.
What changed
The underlying behaviour did not move. Shopify B2B checkout already allowed a company contact to place an order without a surname, and the Payments Apps API already forwarded those sessions with the field absent. What changed is the contract: the payments app request reference now documents family_name as optional for B2B orders in both the shipping and billing address hashes.
That distinction matters in practice. An undocumented optional field is one that integration teams typically discover through a production failure rather than a spec review. Strictly typed clients are the usual casualty here, because a non-nullable string in a generated model will throw on deserialisation before any of your own validation logic runs.
Why it matters
On the B2B side of a Plus store, a rejected payment session is not a recoverable checkout error in the way a declined card is. The buyer sees a generic payment failure, the sales rep hears about it second hand, and the order lands in a support queue instead of the order feed. For merchants running net terms or bank transfer through a third party app, that failure mode is silent enough to persist for weeks.
Company account data is the reason this surfaces at all. B2B buyer records are frequently imported from an ERP or a CRM where the contact is stored as a single name field, a role inbox, or a department. Those records arrive with a given name and nothing else. If you are auditing how company account data flows into checkout, a structured integration review is usually faster than tracing individual failed sessions.
Role-specific impact
- Marketers: no direct campaign impact. The benefit is indirect, in the form of fewer unexplained wholesale checkout drop-offs that get misattributed to pricing or to the buyer experience.
- Developers: audit request validation, JSON schemas, and generated models for a required family_name. Treat the field as nullable for B2B and keep existing handling for direct-to-consumer sessions, which are unaffected.
- Store admins: expect legitimate B2B orders where the buyer surname is blank. Do not treat a missing surname in payout or reconciliation exports as a data quality defect that needs correcting at source.
Use-case example
Real-world scenario
An industrial parts distributor runs 1,400 company accounts on Shopify B2B with a regional bank transfer app handling terms payments. Roughly 6 percent of company contacts were migrated from the legacy ERP with a single name string, which mapped to given_name with family_name empty. The payments app enforced a required surname, so those sessions returned a validation error at the payment step. The team read the failures as intermittent provider instability for two quarters. After relaxing the validation to accept an absent family_name on B2B sessions, roughly 80 previously failing checkouts per quarter completed on the first attempt, and the manual invoice workaround for those accounts stopped being needed.
Implementation checklist
- Identify every code path where your payments app reads shipping_address.family_name or billing_address.family_name.
- Confirm whether validation, schema definitions, or generated type bindings mark the field as required.
- Relax the requirement for B2B sessions and ensure downstream formatting handles an empty surname without producing a trailing space or a null literal.
- Test payment session handling with family_name present, empty, and absent, and confirm the behaviour is identical across all three.
- Review historical failed payment sessions for validation errors that match this pattern, then confirm the affected company accounts can transact.
FAQ
Q: Does this affect direct-to-consumer checkout sessions?
A: No. The optional treatment applies to B2B orders. Consumer checkout continues to behave as it did, so existing validation for those sessions can stay in place.
Q: Do we need to change anything if our app already accepts the field as absent?
A: No change is required. The documentation update simply makes the existing contract explicit, so an app that already tolerates a missing surname is already compliant.
Resources
Payments app request reference
Need guidance? Talk to Makro.