B2B

Source: Shopify API access scopes

B2B only works with the new customer accounts. A store still on legacy customer accounts cannot give buyers a B2B session, and a headless storefront must replace its legacy login code with the Customer Account API authorization flow before it can contextualize requests. Legacy customer accounts are deprecated in favour of new customer accounts, as the Authentication and Access Scopes page explains.

Create a development store with shopify store create dev or from the Dev Dashboard, add products to it, and give the app the scopes above in shopify.app.toml. The store has to be on a plan with B2B capabilities for the examples to work. This page has no development store behind it, so the app configuration was only validated offline, in the section Events and integrations.

companyCreate creates a company and, in the same call, its first location and first contact. The tutorial stresses that a location must be added to attach information such as tax exemptions, and that a contact must exist before any order or draft order can be created for the company. CompanyCreateInput has three parts: company (name, note, externalId, customerSince), companyLocation (CompanyLocationInput, below) and companyContact (firstName, lastName, email, title, locale, phone).

Variables for Cafe Brasa SL, with the Madrid location as the first location and its purchasing manager as the first contact. The reserved domain example.test stands in for a real address, and the tax ID is a placeholder.

Source: Start building for B2B on Shopify, step 1 and companyCreate

userErrors on all company mutations are BusinessCustomerUserError objects with a code from BusinessCustomerErrorCode: RESOURCE_NOT_FOUND, REQUIRED, NO_INPUT, INVALID_INPUT, INVALID, BLANK, TAKEN (for example a duplicate contact email), TOO_LONG, LIMIT_REACHED, FAILED_TO_DELETE, UNEXPECTED_TYPE and INTERNAL_ERROR. Always select code besides message, because message is meant for people and may be translated.

Source: Admin GraphQL mutations (names read from the 2026-10 introspection)

A contact has no permission anywhere until it is assigned a role at a location. Read the available roles from the company, then assign one per location:

The variables give Marta Ruiz the same role at both locations (the IDs are placeholders; read the real role ID from the first query):

Source: companyContactAssignRoles and CompanyContactRoleAssignment

The schema describes role names such as admin or buyer; read the names and IDs from contactRoles instead of hardcoding them. Importing B2B orders needs the same assignment: the customer must have a role at the location named in the order, or the import returns an error.

companies is a normal connection. Its query argument accepts the search syntax of the Admin API, and the sort keys are CREATED_AT, ID, NAME, ORDER_COUNT, SINCE_DATE, TOTAL_SPENT and UPDATED_AT. Count fields return a Count object, not an integer.

Source: companies query

To export every company with its locations and payment terms, use a bulk query, which avoids paginating and throttling by hand; the Bulk Operations page covers the mechanics. The document below was validated, and it follows the restrictions of bulk queries (at most five connections, at most two levels of nesting):

Source: Perform bulk operations with the GraphQL Admin API

Use externalId on companies and locations as the join key with the ERP or CRM, and keep it stable. A bulk company importer is also a natural fit for an app: the Winter '26 Edition even shows Sidekick generating one from a CSV file and creating companies from a prompt, which is a convenience for merchants, not an API.

A company needs one location per place that buys on different terms. CompanyLocationInput takes name, phone, locale, externalId, note, billingAddress and shippingAddress (CompanyAddressInput: address1, address2, city, zip, zoneCode, countryCode, recipient, firstName, lastName, phone), billingSameAsShipping, taxRegistrationId, taxExemptions, taxExempt and buyerExperienceConfiguration. The location’s currency follows its shipping address; without one it follows the shop.

Variables: the Berlin branch ships to Berlin but is invoiced to the Madrid head office.

Source: Manage client company locations, step 1

The addresses are not copied onto draft orders automatically. The start-building tutorial points out that billing and shipping information are not populated from the company location, so an app that creates draft orders should read the addresses from the location and pass them in.

Tax exemptions belong to the location, not the company, because two branches may be taxed differently (the guide’s example is a company with branches that follow different billing and taxation rules). Set the exemption before the location places its first order. The mutation takes the exemptions to add and remove and, since the 2025 tax_exempt change, a taxExempt flag and a taxRegistrationId; TaxExemption has 74 values in 2026-10, mostly Canadian and US provincial and state certificates such as CA_BC_RESELLER_EXEMPTION and CA_STATUS_CARD_EXEMPTION.

Source: Manage client company locations, step 2 and tax_exempt on CompanyLocation

The Spring '26 Edition adds that B2B taxes are calculated automatically for tax-inclusive pricing, and the tax summary webhook and calculation requests now include customer and company metafields (changelog entry of 2026-04-01), which lets a tax app use company data without extra queries.

One query gathers the settings that decide how a location buys: its terms, its catalogs, who may act for it and its store credit. Store credit accounts can be owned by a company location since 2025-09-15, in the Admin and Customer APIs.

Source: CompanyLocation object reference and Store credit for company locations

The location is also a market condition. A market can name specific company locations, or all of them in a region, and Shopify resolves the most specific market first, with the company location ahead of the retail location and the region; the Markets and Internationalization page explains the precedence and lineage rules, and notes that CompanyLocation.market is deprecated.

A catalog answers two questions for a context: which products can the buyer see, and what do they cost. It does so by pointing at two optional objects. A publication is the set of products and collections visible in the catalog. A price list holds prices for variants: a percentage adjustment of the base price (parent), plus fixed prices for individual variants, plus quantity rules and price breaks. Catalog is an interface with three implementations, chosen by the context:

Source: Catalog interface and About catalogs for different markets

Do not confuse these B2B catalogs with Shopify Catalog and the Catalog API, which are unrelated products for product discovery by AI agents. Their changelog entries appear in the same feed, but they have nothing to do with price lists.

CatalogContextInput accepts exactly one kind of context per call (MUST_PROVIDE_EXACTLY_ONE_CONTEXT_TYPE), and catalogContextUpdate must match the existing kind (CONTEXT_DRIVER_MISMATCH). A location that is already in the catalog cannot be added again (CONTEXT_ALREADY_ASSIGNED_TO_CATALOG). The catalog guide recommends managing B2B catalogs through markets when the shop uses the Markets API, instead of linking them to individual company locations.

catalogCreate needs a title, a status (ACTIVE, DRAFT or ARCHIVED; the field is required) and a context. The priceListId and publicationId are optional and can be attached later. Pocket Coffee’s wholesale catalog serves both Cafe Brasa locations:

Source: Start building for B2B on Shopify, step 2 and catalogCreate

A catalog is created without a price list and without a publication when you leave both out. The 2026-10 reference says a company location catalog that only needs custom pricing should be created with a price list and without a publication, and that without a publication availability is determined by the sales channel. The older catalog guide warns that customers logged in to a B2B account see no products for a location whose catalog has no publication. The two statements describe different generations of the same feature. For a catalog that must restrict products, create a publication explicitly and test with a buyer on the target plan; for a pricing-only catalog, check on a development store that the products you expect are visible before relying on the reference wording.

A price list belongs to one catalog (error CATALOG_TAKEN otherwise) and has a currency. Its parent gives a percentage adjustment of the prices it inherits, and settings.compareAtMode decides what happens to the compare-at price: ADJUSTED applies the same adjustment, NULLIFY removes it. The adjustment type is PERCENTAGE_DECREASE or PERCENTAGE_INCREASE; the schema notes that in PriceListAdjustment.value, positive numbers reduce prices and negative numbers increase them, so read the type and the value together.

Source: Manage B2B catalogs, step 1

If a catalog has no price list, buyers get the initial variant prices converted to the market currency. To move an existing price list to another catalog, use priceListUpdate with a new catalogId; the price list is detached from its previous catalog, and if that catalog depended on it, it becomes a publishing-only catalog on store default prices, so give the old catalog a new price list or accept the change. The PriceList.contextRule field was deprecated in API version 2023-04 and is not in the 2026-10 schema (querying it is rejected, see the checks at the end of the page); migrate any app that still uses it to catalogs.

A publication decides the products. publicationCreate takes the catalogId, a defaultState (an empty publication or one prepopulated with every product) and autoPublish (add new products automatically). publicationUpdate adds and removes products in batches of at most 50.

Source: Manage B2B catalogs, step 2

Changing the publication of a catalog with catalogUpdate leaves the previous publication in the system, orphaned, unless the app deletes it. The guide’s recipe is to read the current publication ID, update the catalog with the new publication, then call publicationDelete on the old one. catalogDelete has a deleteDependentResources argument for removing the price list and publication with the catalog.

Source: Manage B2B catalogs: preventing orphaned resources

A variant published to the catalog without a fixed price gets the percentage adjustment of the price list. Set a fixed price when the negotiated price is not a clean percentage. priceListFixedPricesAdd is an add-and-replace operation: a variant that already has a fixed price on the list is overwritten, and a request holds at most 250 prices. priceListFixedPricesDelete takes up to 250 variant IDs, after which the adjustment applies again. The list also has priceListFixedPricesUpdate and priceListFixedPricesByProductUpdate for mixed changes.

Pocket Coffee negotiates 22.00 EUR for the 1 kg Brazil bag (variant PC-BRA-WHL-1KG, list price 29.90 EUR):

Source: Manage B2B catalogs, step 3

Wholesale usually comes with order-size rules. A QuantityRule has a minimum, an optional maximum and an increment: only quantities divisible by the increment are valid, the minimum must be a multiple of the increment, and the maximum too. A QuantityPriceBreak gives a lower price from a minimum quantity. quantityPricingByVariantUpdate changes fixed prices, rules and breaks in one request, runs the deletions before the additions, and applies nothing if any change fails. Quantity rules and breaks are accepted only for company location catalogs and for catalogs on compatible markets (CATALOG_CONTEXT_DOES_NOT_SUPPORT_QUANTITY_RULES).

Cafe Brasa buys the Colombia 1 kg bag (variant PC-COL-WHL-1KG) in multiples of two, at least four and at most a hundred, at 21.50 EUR from ten bags and 20.00 EUR from twenty:

Source: quantityPricingByVariantUpdate

The schema’s own text for the maximum says it "must be lower than or equal to the minimum", which cannot be what is meant: the maximum is the upper bound and must be at least the minimum. Treat the rule as minimum less than or equal to maximum, both divisible by the increment, with the increment less than or equal to the minimum.

Read the result back to confirm what the price list holds. The originType field of a price tells a fixed price (FIXED) from one computed from the adjustment (RELATIVE), and quantity rules report whether they were set explicitly:

Source: PriceList object reference

A company location can be in several catalogs, and the rules for combining them are simple. A buyer sees the products that are published in at least one applicable catalog, and when several catalogs price the same variant, the lowest listed price applies. The developer docs build a scaling pattern on this: keep pricing-only catalogs (one per price list) and publication-only catalogs (one per assortment) and assign several to each location. A merchant with 50 pricing tiers and 10 assortments then manages 60 catalogs instead of 500 full ones. The pattern is shared with Markets, and on plans below Plus the limit of three B2B catalogs applies, so it matters most on Plus.

How visibility, price and quantity rule are resolved for a location with two catalogs.

Source: Manage B2B catalogs: managing multiple catalogs per company location

The model below encodes only the documented rules, so a configuration can be reasoned about before it is sent to a shop. It is a local illustration, not Shopify’s engine: it does not know about rounding, exchange rules or market inheritance, and how price breaks of one catalog combine with the lower price of another is not documented, so it takes the lowest result.

Running it for six requests gave the following results (unit prices in EUR):

Source: Manage B2B catalogs: customer experience

Source: CatalogUserError (codes read from the 2026-10 introspection)

paymentTermsTemplates lists the templates of the shop, optionally filtered by PaymentTermsType. A template has an id, a name, a translatedName, a description, a type and, for net terms, dueInDays. The template IDs are specific to a shop, so read them instead of copying the ID from a tutorial.

Source: paymentTermsTemplates and PaymentTermsType

Set the terms through the location’s buyerExperienceConfiguration. Besides paymentTermsTemplateId it holds checkoutToDraft, editableShippingAddress and deposit:

Variables: Madrid pays net 30 (the template ID comes from the query above) with a 20 percent deposit, and does not go through merchant review:

Source: Manage client company locations, step 3

A draft order can carry terms at creation (DraftOrderInput.paymentTerms and deposit), and paymentTermsCreate, paymentTermsUpdate and paymentTermsDelete change terms on an existing order or draft order. paymentTermsCreate takes the referenceId of the order or draft order and PaymentTermsCreateInput with the template ID and the schedules. The result exposes due, overdue and the paymentSchedules with issuedAt, dueAt, totalBalance and balanceDue, which are the fields to poll for accounts-receivable dashboards.

Source: paymentTermsCreate

PaymentTermsCreateUserErrorCode has a single value, PAYMENT_TERMS_CREATION_UNSUCCESSFUL, so the message is the only clue; the usual causes are a template type whose required date is missing from the schedule, or a reference that cannot take terms. The webhook topics payment_terms/create, payment_terms/update and payment_terms/delete fire when terms change and need read_payment_terms.

A payment customization Function can set terms per checkout instead of per location, which is how rules such as "net 30 only above 500 EUR" are expressed. On 2025-06-18 the target cart.payment-methods.transform.run gained the paymentTermsSet operation, which defines net, fixed or event-based terms for the order, with an optional deposit. The operation is only available on Plus stores. The three term types have these inputs:

Returning no operation leaves the checkout alone, and returning paymentTermsSet with no paymentTerms removes terms. The Function below requests net 30 with a 20 percent deposit for company orders of 500 EUR or more, and does nothing for retail buyers or smaller company orders. It reads the buyer’s purchasingCompany from the cart.

Source: Payment Customization Function API

The extension file, with the target and the input query, is:

Built with shopify app build --no-input (the JavaScript builder ran javy and produced a 1,762-byte function.wasm) and run three times with shopify app function run. A company order of 1,196.00 EUR returned one operation with net 30 and a 20 percent deposit; the 119.60 EUR company order and a 29.90 EUR retail cart both returned an empty operations list. The runner reported 173,711 instructions for the first run against the 11 million limit. A Function can be built and run offline; deploying it, installing it and selecting it at a real checkout needs a store and was not done.

Source: Define payment terms conditionally at checkout and Payment Customization Function API

Two more payment features arrived in the Editions and are not described in the developer reference as API fields: a Flow action that charges vaulted payment methods of B2B customers on fulfillment, due dates or invoicing (Spring '26), and ACH payments with Shopify Payments for US Plus merchants (Winter '26). A changelog entry of 2026-09-15 also makes family_name optional for B2B orders in Payments Apps API requests.

Draft orders are the B2B "quote": a merchant or an app prepares an order for a purchasing entity, checks the totals, sends an invoice and, when the company agrees or pays, completes it into an order. The tutorial is a four-call sequence: draftOrderCalculate, draftOrderCreate, draftOrderInvoiceSend and draftOrderComplete. The purchasing company goes in purchasingEntity.purchasingCompany, which needs all three of companyId, companyLocationId and companyContactId. The input also carries poNumber, paymentTerms and deposit, lineItems (by variantId and quantity, or custom items), billingAddress and shippingAddress, tags, note, taxExempt and reserveInventoryUntil.

The calculation previews taxes and totals without saving anything, so use it to show the quote to the merchant first:

The first Cafe Brasa order, twelve bags of Colombia 1 kg, on the location’s terms (the same variables serve the calculation and the creation):

Source: Use draft orders and Start building for B2B on Shopify, step 3

The guide’s examples pass a price with originalUnitPriceWithCurrency and a title for a custom line. A line built from variantId takes the price from the catalog of the purchasing location, so prefer it; pass an explicit price only for custom lines. Sending an invoice and completing a B2B draft order work exactly as they do for consumer draft orders. The draft order reference covers the remaining options, such as inventory reservation and payment status.

A merchant moving from another system can import history so that buyers see their full order list in their account. orderCreate accepts a B2B order when the input names both companyLocationId and a customer to associate. The imports have strict prerequisites: the company, location, contact and products must already exist in Shopify, and the customer must hold a role at that location; otherwise the call returns an error. Always send priceSet for each line: when it is omitted the API fills it from the current variant price, which gives wrong history. The input has poNumber for the original purchase order number, processedAt, financialStatus, currency, transactions, sourceName and sourceIdentifier.

Source: Import B2B orders

Reading B2B orders back is done from the location (or the company or the contact), which avoids searching the order list by customer:

Source: CompanyLocation object reference

The Customer Account API authorization flow produces an access_token for the customer; this is the customerAccessToken of the later steps. With that token, a Customer Account API query returns the company contacts of the customer and the locations they can buy for. If the result has one location, keep its ID. If it has several, build a location selector, store the chosen ID and redirect there after login. A location is shown with its address and the payment terms it will use, so the buyer knows what the checkout will do.

This query was validated against the Customer Account API schema 2026-04 from @shopify/hydrogen-react 2026.4.4, because the schema for 2026-10 is not served for download; the fields it uses are in the 2026-10 reference pages as well.

Source: Headless with B2B, step 2 and Customer Account API CompanyContact

Pass a buyer to the @inContext directive to contextualize any query. BuyerInput has two fields, customerAccessToken (required) and companyLocationId. A contextualized product query returns the price for the buyer’s location, the quantityRule and the quantityPriceBreaks of each variant, which are the fields a quantity selector and a volume table need.

Source: Headless with B2B, step 3

The variable above shows an environment placeholder where a real request carries the buyer’s token. A B2B response depends on the token and the location, so a server that caches responses by URL would serve one buyer’s prices to another; the guide’s caution says to disable caching on routes that return buyer-specific data, and it links to the caching guide of the legacy Hydrogen framework for how to do that. The @inContext directive has other arguments (country, language, channelId, preferredLocationId, visitorConsent); in cart operations buyer and country are ignored, and only language still applies.

Because a cart ignores @inContext(buyer:), set the buyer on the cart itself. CartBuyerIdentityInput has email, phone, countryCode, customerAccessToken, companyLocationId and preferences. After the call, the cart’s buyerIdentity.purchasingCompany shows the company, location and contact, and the checkoutUrl leads to a B2B checkout.

Source: Headless with B2B, step 4

Changing the buyer identity of a cart that already has lines can make it invalid. Products not published for the new location are removed, and products that stay but fall under different quantity rules are left unchanged. Reading the cart does not fail, but updating it may, and a buyer who goes to checkout with an invalid cart sees the problems as an error. The codes to handle in userErrors and warnings:

Source: cartBuyerIdentityUpdate (codes read from the 2026-10 Storefront schema) and New CartErrorCode: BUYER_CANNOT_PURCHASE_FOR_COMPANY_LOCATION

Headless also allows a gated store, where visitors can browse products but see no price and cannot order. Include the price in the query, and render the add-to-cart button, only when there is a valid session with a stored company location ID. The same principle as the Liquid customer.b2b? check applies, enforced in your own code. Hydrogen is a framework-agnostic toolkit as of 2026-10; the Storefront API and Headless page explains how it holds the Storefront and Customer Account clients that these queries run on.