shopify-b2b-wholesale

Shopify B2B & Wholesale

Overview

Shopify Plus B2B features let you create separate wholesale experiences with company accounts, custom catalogs, and tiered pricing. This skill covers the full B2B setup: companies, catalogs, price lists, and checkout configuration using the GraphQL Admin API. Requires a Shopify Plus plan.

Prerequisites

• Shopify Plus plan (B2B features are Plus-only)
• Access scopes: read_customers, write_customers, read_products, write_products, read_orders
• B2B enabled in Shopify admin (Settings > B2B)
• API version 2023-10 or later (B2B mutations stabilized)

Instructions

Step 1: Create a B2B Company

Use companyCreate with CompanyCreateInput — requires company (name, note), companyContact (email, firstName, lastName), and companyLocation (name, billingAddress, shippingAddress):

await client.request(COMPANY_CREATE, {
  variables: {
    input: {
      company: { name: "Acme Wholesale Inc", note: "Tier 1 partner" },
      companyContact: { email: "buyer@acme.com", firstName: "Jane", lastName: "Doe" },
      companyLocation: {
        name: "Headquarters",
        billingAddress: { address1: "123 Commerce St", city: "Austin", provinceCode: "TX", countryCode: "US", zip: "78701" },
        shippingAddress: { address1: "123 Commerce St", city: "Austin", provinceCode: "TX", countryCode: "US", zip: "78701" },
      },
    },
  },
});
// Always check userErrors in response — returns code like COMPANY_NOT_FOUND, INVALID

See references/company-management.md for the full mutation, additional contacts, locations, and roles.

Step 2: Create a Catalog

Catalogs link products to specific companies. Use catalogCreate with a title, status, and context.companyLocationIds:

await client.request(CATALOG_CREATE, {
  variables: {
    input: {
      title: "Wholesale Tier 1",
      status: "ACTIVE",
      context: { companyLocationIds: ["gid://shopify/CompanyLocation/123456"] },
    },
  },
});

Step 3: Set Wholesale Pricing

Create a price list with priceListCreate. Use PERCENTAGE_DECREASE for blanket discounts or priceListFixedPricesAdd for per-variant overrides:

// 30% off all products in this catalog
await client.request(PRICE_LIST_CREATE, {
  variables: {
    input: {
      name: "Wholesale 30% Off",
      currency: "USD",
      parent: { adjustment: { type: "PERCENTAGE_DECREASE", value: 30 } },
      catalogId: "gid://shopify/Catalog/789",
    },
  },
});

For fixed price overrides, volume pricing, and multi-currency, see references/catalog-pricing.md.

Step 4: B2B Checkout Configuration

B2B orders use draftOrderCreate with purchaseOrder number and purchasingEntity linking to the company. Key fields:

await client.request(DRAFT_ORDER_CREATE, {
  variables: {
    input: {
      purchaseOrder: "PO-2026-0042",
      lineItems: [{ variantId: "gid://shopify/ProductVariant/123", quantity: 100 }],
      purchasingEntity: {
        purchasingCompany: {
          companyId: "gid://shopify/Company/456",
          companyContactId: "gid://shopify/CompanyContact/789",
          companyLocationId: "gid://shopify/CompanyLocation/012",
        },
      },
      paymentTerms: { paymentTermsTemplateId: "gid://shopify/PaymentTermsTemplate/1" },
    },
  },
});

Payment terms templates: Due on receipt, Net 15, Net 30, Net 45, Net 60, Net 90. Query available templates with paymentTermsTemplates.

See references/b2b-checkout.md for the full draft order flow, invoice sending, and vaulted payments.

Output

• B2B company created with contact and billing/shipping addresses
• Catalog linked to specific company locations
• Wholesale price list with percentage or fixed pricing
• Draft orders with purchase order numbers and payment terms

Error Handling

Error	Cause	Solution
COMPANY_NOT_FOUND	Invalid company GID	Verify the company ID exists via companyQuery
CATALOG_LIMIT_EXCEEDED	Max catalogs per context reached	Remove unused catalogs or upgrade plan
PRICE_LIST_NOT_FOUND	Price list not linked to catalog	Ensure catalogId is set on price list
B2B_NOT_ENABLED	B2B feature not activated	Enable B2B in Shopify admin Settings > B2B (requires Plus)
COMPANY_CONTACT_NOT_FOUND	Contact not associated with company	Create contact via companyContactCreate first
INVALID_PURCHASING_ENTITY	Missing company/contact/location in draft order	All three IDs required in purchasingCompany

Examples

Onboarding a New Wholesale Partner

Create a B2B company with multiple contacts, locations, and roles for a new wholesale account joining your program.

See Company Management for the full mutation and multi-contact setup.

Setting Up Tiered Wholesale Pricing

Configure percentage-based discounts for standard wholesalers and fixed per-variant overrides for VIP partners using price lists.

See Catalog Pricing for percentage, fixed price, and volume pricing strategies.

Processing a B2B Purchase Order

Create a draft order with a PO number, Net 30 payment terms, and company association for a wholesale buyer.

See B2B Checkout for the full draft order flow, invoice sending, and vaulted payments.

Resources

• B2B on Shopify
• companyCreate Mutation
• catalogCreate Mutation
• priceListCreate Mutation
• B2B Checkout