Wholesale

Manage wholesale pricing tiers, applications, and B2B customer approvals.

Overview

The wholesale system provides a complete B2B pricing layer on top of your existing catalog. Set tiered pricing per product, accept and review wholesale applications, and automatically apply volume discounts for approved customers at checkout.

pricing_tiers

Volume-based price breaks per product. Define minimum quantities and unit prices for each tier.

applications

B2B customers apply for wholesale access. Review and approve or reject with optional notes.

wholesale_customers

Approved customers who see wholesale pricing at checkout and in their storefront session.

order_minimums

Configurable minimum order values and quantities to enforce wholesale purchasing rules.

Set Pricing Tiers

Create volume-based pricing tiers for any product. Each tier specifies a minimum quantity and a unit price. When a wholesale customer orders above the threshold, the lower price applies automatically.

const whale = new WhaleClient("wk_live_...");

// Create tiered pricing for a product
const tiers = [
  {
    product_id: "prod_ceramic_mug_001",
    tier_name: "Small Batch",
    minimum_quantity: 25,
    unit_price: 8.50
  },
  {
    product_id: "prod_ceramic_mug_001",
    tier_name: "Medium Batch",
    minimum_quantity: 100,
    unit_price: 6.75
  },
  {
    product_id: "prod_ceramic_mug_001",
    tier_name: "Bulk",
    minimum_quantity: 500,
    unit_price: 4.99
  }
];

for (const tier of tiers) {
  await whale.wholesalePricing.create(tier);
}

// Response (for "Medium Batch")
{
  "object": "wholesale_pricing",
  "id": "wpt_c3d4e5f6-a7b8-9012-cdef-345678901234",
  "product_id": "prod_ceramic_mug_001",
  "tier_name": "Medium Batch",
  "minimum_quantity": 100,
  "unit_price": 6.75,
  "retail_price": 14.99,
  "discount_percentage": 54.97,
  "created_at": "2026-03-10T09:30:00.000Z"
}

Application Review Flow

B2B customers submit wholesale applications with their business details. Applications start in pending status. When approved, the customer profile is automatically updated to enable wholesale pricing on their account.

// Submit a wholesale application
const application = await whale.wholesaleApplications.create({
  customer_id: "cust_d4e5f6a7",
  business_name: "Riverside Coffee Co.",
  business_type: "retail",
  tax_id: "87-1234567",
  estimated_monthly_volume: 500,
  notes: "Three retail locations in Portland, OR"
});

// Approve the application — auto-updates customer profile
await whale.wholesaleApplications.update("wsa_e5f6a7b8...", {
  status: "approved",
  approved_tier: "Medium Batch",
  credit_limit: 10000,
  payment_terms: "net_30",
  reviewer_notes: "Verified business license, 3 locations confirmed"
});

// Response
{
  "object": "wholesale_application",
  "id": "wsa_e5f6a7b8-c9d0-1234-ef56-789012345678",
  "customer_id": "cust_d4e5f6a7",
  "business_name": "Riverside Coffee Co.",
  "status": "approved",
  "approved_tier": "Medium Batch",
  "credit_limit": 10000,
  "payment_terms": "net_30",
  "customer_updated": true,
  "approved_at": "2026-03-10T14:00:00.000Z"
}

// Reject an application
await whale.wholesaleApplications.update("wsa_f6a7b8c9...", {
  status: "rejected",
  reviewer_notes: "Unable to verify business license"
});

List Wholesale Customers

Query all approved wholesale customers with their tier assignments, credit limits, and order history summaries. Use this to monitor account health and identify top wholesale buyers.

const customers = await whale.wholesaleCustomers.list({
  limit: 25,
  sort: "lifetime_value",
  order: "desc"
});

// Response
{
  "object": "list",
  "data": [
    {
      "customer_id": "cust_d4e5f6a7",
      "business_name": "Riverside Coffee Co.",
      "approved_tier": "Medium Batch",
      "credit_limit": 10000,
      "credit_used": 3250,
      "payment_terms": "net_30",
      "lifetime_orders": 12,
      "lifetime_value": 28450,
      "approved_at": "2026-03-10T14:00:00.000Z"
    },
    {
      "customer_id": "cust_a1b2c3d4",
      "business_name": "Mountain Goods Supply",
      "approved_tier": "Bulk",
      "credit_limit": 25000,
      "credit_used": 0,
      "payment_terms": "net_15",
      "lifetime_orders": 3,
      "lifetime_value": 12680,
      "approved_at": "2026-02-20T10:30:00.000Z"
    }
  ],
  "total_count": 8,
  "has_more": false
}

API Reference

Method	Path	Description
GET	/v1/stores/{store_id}/wholesale-pricing	List all wholesale pricing tiers across products.
POST	/v1/stores/{store_id}/wholesale-pricing	Create a pricing tier for a product.
PATCH	/v1/stores/{store_id}/wholesale-pricing/{id}	Update tier name, quantity threshold, or unit price.
DELETE	/v1/stores/{store_id}/wholesale-pricing/{id}	Remove a pricing tier.
GET	/v1/stores/{store_id}/wholesale-applications	List applications. Filter by status (pending, approved, rejected).
POST	/v1/stores/{store_id}/wholesale-applications	Submit a new wholesale application.
PATCH	/v1/stores/{store_id}/wholesale-applications/{id}	Approve or reject an application.
GET	/v1/stores/{store_id}/wholesale-customers	List all approved wholesale customers.