Skip to main content

Shipping Object

Overview​

The shipping object contains detailed information about shipping methods and delivery options used in e-commerce events, enabling comprehensive logistics tracking, delivery analytics, and shipping performance optimization. This object is used within e-commerce events to track shipping costs, delivery preferences, and fulfillment methods across the customer journey.

Each shipping object represents a single shipping method or delivery option with its associated costs, tax information, delivery timeframes, and custom properties that enable precise logistics tracking and shipping analytics.

Core Structure​

The shipping object consists of several logical groups of properties:

  • Core Properties - Essential shipping identification and cost information
  • Tax Information - Tax calculations and tax-inclusive pricing
  • Shipping Classification - Method types and delivery categories
  • Currency Support - Multi-currency shipping costs and exchange rates

Complete Reference​

shipping[0] object

name string recommended

info

Shipping method name

name: "SHIPPING_NAME"

value number required

info

Shipping cost value

value: 12.99

tax_included boolean recommended

info

Whether shipping cost includes taxes

tax_included: true

tax_percent number recommended

info

Tax percentage for shipping (0-100)

tax_percent: 21

id string|number

info

Shipping method identifier.

id: "SHIPPING_INTERNAL_ID"

type string

info

Shipping type (e.g., "standard", "express", "next_day")

type: "standard"

currency string required-if-applicable

info

Currency code. Specifies the currency code when it differs from event.currency.

currency: "USD"

exchange_rate number

info

Custom exchange rate for multi-currency. Default has value 1. Specifies when it differs from event.exchange_rate.

exchange_rate: 1

Implementation Examples​

{
  // Standard ground delivery
  name: "Standard Ground Shipping",
  value: 15.99,
  tax_included: true,
  tax_percent: 8.25,
  id: "SHIPPING_STANDARD_001",
  type: "standard",
  currency: "USD",
  exchange_rate: 1
}

Shipping Types​

The type field categorizes shipping methods for analytics and optimization:

Standard shipping methods for regular delivery:

{
  type: "standard",           // Standard ground shipping
  type: "economy",            // Economy/slow shipping
  type: "ground",             // Ground transportation
  type: "regular",            // Regular delivery timeframe
  type: "bulk"                // Bulk or freight shipping
}

Tax Configuration​

Shipping objects support comprehensive tax calculation for compliance:

Tax-Inclusive Pricing​

{
  name: "Standard Shipping",
  value: 15.99,           // Total price including tax
  tax_included: true,     // Tax is included in value
  tax_percent: 8.25,      // Tax rate applied
  currency: "USD"
}

Tax-Exclusive Pricing​

{
  name: "Express Delivery",
  value: 25.00,           // Base price before tax
  tax_included: false,    // Tax not included in value
  tax_percent: 19,        // Tax to be added
  currency: "EUR"
}

Tax-Free Shipping​

{
  name: "Free Shipping Promotion",
  value: 0.00,
  tax_included: true,
  tax_percent: 0,         // No tax on free shipping
  currency: "USD"
}

Multi-Currency Support​

Shipping costs support multi-currency transactions with exchange rates:

// USD Base Currency
{
  name: "Standard US Shipping",
  value: 12.99,
  currency: "USD",
  exchange_rate: 1
}

// EUR with Exchange Rate
{
  name: "European Express",
  value: 19.99,
  currency: "EUR",
  exchange_rate: 1.08      // EUR to USD conversion
}

// Local Currency
{
  name: "Local Delivery",
  value: 45.00,
  currency: "RON",
  exchange_rate: 0.22      // RON to USD conversion
}

Shipping Method Examples​

Domestic Shipping Options​

[
  {
    name: "Standard Ground (5-7 days)",
    value: 8.99,
    tax_included: true,
    tax_percent: 8.25,
    type: "standard",
    id: "DOM_STD_001"
  },
  {
    name: "Express (2-3 days)",
    value: 18.99,
    tax_included: true,
    tax_percent: 8.25,
    type: "express",
    id: "DOM_EXP_001"
  },
  {
    name: "Overnight Delivery",
    value: 34.99,
    tax_included: true,
    tax_percent: 8.25,
    type: "overnight",
    id: "DOM_OVER_001"
  }
]

International Shipping Options​

[
  {
    name: "International Standard (7-14 days)",
    value: 29.99,
    tax_included: false,
    tax_percent: 0,           // Tax handled by destination country
    type: "international",
    id: "INTL_STD_001",
    currency: "USD"
  },
  {
    name: "DHL Express International (3-5 days)",
    value: 89.99,
    tax_included: false,
    tax_percent: 0,
    type: "international_express",
    id: "INTL_DHL_001",
    currency: "USD"
  },
  {
    name: "FedEx Priority Worldwide",
    value: 124.99,
    tax_included: false,
    tax_percent: 0,
    type: "worldwide",
    id: "INTL_FEDEX_001",
    currency: "USD"
  }
]

Alternative Fulfillment Methods​

[
  {
    name: "Store Pickup - Downtown Location",
    value: 0.00,
    tax_included: true,
    tax_percent: 0,
    type: "pickup",
    id: "PICKUP_DT_001"
  },
  {
    name: "Curbside Pickup",
    value: 0.00,
    tax_included: true,
    tax_percent: 0,
    type: "curbside",
    id: "PICKUP_CURB_001"
  },
  {
    name: "Digital Download",
    value: 0.00,
    tax_included: true,
    tax_percent: 0,
    type: "digital",
    id: "DIGITAL_001"
  }
]

Usage in E-commerce Events​

The shipping object is used in e-commerce events within the shipping array:

Integration Patterns​

Single Shipping Method​

// Single shipping option selected
{
  shipping: [
    {
      name: "Express Delivery",
      value: 24.99,
      tax_included: true,
      tax_percent: 8.25,
      type: "express",
      currency: "USD"
    }
  ]
}

Multiple Shipping Methods​

// Split shipments or multiple carriers
{
  shipping: [
    {
      name: "Standard Shipping - Package 1",
      value: 12.99,
      tax_included: true,
      tax_percent: 8.25,
      type: "standard",
      id: "SHIP_PKG1_001"
    },
    {
      name: "Express Shipping - Package 2",
      value: 19.99,
      tax_included: true,
      tax_percent: 8.25,
      type: "express",
      id: "SHIP_PKG2_001"
    }
  ]
}

Free Shipping with Threshold​

// Free shipping promotion
{
  shipping: [
    {
      name: "Free Standard Shipping (Order over $50)",
      value: 0.00,
      tax_included: true,
      tax_percent: 0,
      type: "free",
      id: "FREE_PROMO_001"
    }
  ]
}

Best Practices​

Data Quality​

  • Accurate Costs - Ensure shipping values reflect real costs including taxes
  • Consistent Naming - Use standardized shipping method names across events
  • Complete Tax Information - Include accurate tax calculations for compliance
  • Currency Consistency - Match shipping currency with order currency when possible

Performance Optimization​

  • Essential Data First - Prioritize required fields for fast checkout implementation
  • Method Optimization - Track shipping method performance and customer preferences
  • Cost Analysis - Monitor shipping costs impact on conversion rates
  • Delivery Analytics - Analyze delivery performance and customer satisfaction

Customer Experience​

  • Clear Naming - Use descriptive shipping method names with timeframes
  • Transparent Pricing - Display total costs including taxes and fees
  • Method Comparison - Provide clear comparison of delivery options
  • Free Shipping Strategy - Optimize free shipping thresholds for conversion

Compliance and Accuracy​

  • Tax Compliance - Ensure accurate tax calculations for shipping costs
  • International Regulations - Follow customs and duty requirements for international shipping
  • Currency Accuracy - Use appropriate exchange rates for multi-currency shipping
  • Cost Validation - Validate shipping costs against carrier rates