Wholesale Orders

Wholesale orders in ShipHero are designed to handle B2B transactions, often involving EDI (Electronic Data Interchange) integrations with major retailers. This page covers the creation of wholesale orders and explains the specific EDI fields that are required for proper label generation and compliance.

Creating Wholesale Orders

To create a wholesale order, use the wholesale_order_create mutation. This mutation is specifically designed for B2B transactions and includes fields that are not available in regular order creation.

Basic Wholesale Order Creation

mutation CreateWholesaleOrder($data: CreateWholesaleOrderInput!) {
  wholesale_order_create(data: $data) {
    complexity
    wholesale_order {
      id
      legacy_id
      fulfillment_flow
      shipping_option
      picking_flow
      status
      status_message
      order_type
      gs1_labels_required
      trading_partner_id
      trading_partner_name
      store_location_number
      department
      wholesale_shipping_details {
        id
        scac
        carrier
        shipping_method
        bill_of_lading
        cost
        trailer_number
        pro_number
      }
      wholesale_line_items {
        edges {
          node {
            id
            line_item {
              sku
              partner_line_item_id
            }
          }
        }
      }
    }
  }
}

Example Variables

{
  "data": {
    "order_number": "WO-12345",
    "partner_order_id": "WO-12345-pid",
    "shop_name": "B2B Channel",
    "order_date": "2025-12-09T00:00:00",
    "required_ship_date": "2025-12-15T00:00:00",
    "total_tax": "5.00",
    "total_discounts": "0.00",
    "total_price": "205.00",
    "currency": "USD",
    "email": "wholesale@example.com",
    "profile": "wholesale",
    "shipping_lines": {
      "title": "FREIGHT",
      "price": "25.00"
    },
    "shipping_address": {
      "address1": "1000 Corporate Blvd",
      "city": "Los Angeles",
      "state": "CA",
      "country": "US",
      "zip": "90210",
      "first_name": "Warehouse",
      "last_name": "Manager"
    },
    "billing_address": {
      "address1": "1000 Corporate Blvd",
      "city": "Los Angeles",
      "state": "CA",
      "country": "US",
      "zip": "90210",
      "first_name": "Warehouse",
      "last_name": "Manager"
    },
    "line_items": [
      {
        "sku": "PRODUCT-123",
        "partner_line_item_id": "LINE-PRODUCT-123",
        "quantity": 10,
        "price": "18.00",
        "quantity_pending_fulfillment": 10,
        "warehouse_id": "129172"
      }
    ],
    "wholesale_shipping_details": {
      "carrier": "freight_company",
      "shipping_method": "ltl",
      "pro_number": "PRO123456",
      "trailer_number": "TRL789012",
      "bill_of_lading": "BOL345678",
      "cost": 150
    },
    "picking_flow": "DESKTOP",
    "shipping_option": "FREIGHT",
    "gs1_labels_required": true,
    "trading_partner_id": "TARGET001",
    "trading_partner_name": "Target Corporation",
    "department": "APPAREL",
    "store_location_number": "1234"
  }
}

EDI-Specific Fields

When working with major retailers through EDI connections, several specific fields are crucial for proper order processing and label generation:

GS1 Labels

gs1_labels_required - This boolean field indicates whether GS1-compliant shipping labels are required for this order. GS1 labels contain standardized barcodes and data elements that major retailers use for automated receiving and inventory management.

When gs1_labels_required is set to true, you must also provide:

trading_partner_name - The name of the retailer/trading partner (e.g., “Target Corporation”, “Walmart Inc.”)
trading_partner_id - A unique identifier for the trading partner, provided by ShipHero when the retailer connection is established

Important

The trading_partner_id is provided by ShipHero’s operations team when a new retailer EDI connection is set up. This ID is specific to each retailer and ensures that the correct GS1 label format and data elements are used.

Important

Once setting up your retailer connection, you will be required to add there a GS1 company prefix. If you want to overwrite it at order level, you might want to use the wholesale_shipping_details.gs1_company_prefix field.

Store and Department Information

Some retailers require additional identification fields for their internal routing and processing:

department - Specifies the department within the retailer where the merchandise should be routed. This is often required for large retailers with multiple departments (e.g., “APPAREL”, “ELECTRONICS”, “HOME”).

store_location_number - The specific store or distribution center number where the goods should be delivered. This field is particularly important for store-direct shipments.

Wholesale Shipping Details

The wholesale_shipping_details object contains freight and logistics information specific to B2B shipments:

scac - Standard Carrier Alpha Code, a unique identifier for transportation companies
carrier - The name of the shipping carrier
shipping_method - The method of shipment (e.g., “ltl” for Less Than Truckload, “ftl” for Full Truckload)
bill_of_lading - The BOL number for freight shipments
pro_number - Progressive number used by carriers for tracking
trailer_number - The trailer identification number
cost - The shipping cost for the order
gs1_company_prefix - The GS1 company prefix for the retailer. Use it only to overwrite the default GS1 company prefix (set as connection level).

Best Practices

Setting Up EDI Fields

Coordinate with ShipHero Operations - Before using GS1 labels, work with ShipHero’s operations team to set up the retailer connection and obtain the correct trading_partner_id.
Validate Retailer Requirements - Each retailer may have specific requirements for department codes, store numbers, and label formats. Verify these requirements before implementation.
Test Label Generation - Always test GS1 label generation in a sandbox environment before going live with a new retailer integration.

Common Pitfalls

Missing Trading Partner Setup - Attempting to use gs1_labels_required: true without proper trading partner configuration will result in errors.
Incorrect Department Codes - Using invalid or outdated department codes can cause rejections at retailer receiving docks.
Missing Freight Information - B2B shipments often require complete freight details for proper processing.

Updating Wholesale Orders

Wholesale orders can be updated using the wholesale_order_update mutation:

mutation UpdateWholesaleOrder($data: UpdateWholesaleOrderInput!) {
  wholesale_order_update(data: $data) {
    complexity
    wholesale_order {
      id
      order_id
      reference_fields
      picking_flow
      pickup_date
      preparation_date
      shipping_option
    }
  }
}

Common update scenarios include:

Updating pickup or preparation dates
Changing shipping options
Adding reference fields for tracking
Modifying picking flow preferences

For more detailed examples of wholesale order mutations, see the Examples page.

Merge Orders