ValidationIssue

Business logic issues that allow cart creation but require buyer action to complete payment.

Use Validation Issues when:

• Cart can be created but buyer needs to make updates to complete payment
• Cart was already created but has business logic problems
• Items need updates, addresses need completion, or policies require acceptance

Consolidated validation issue system with 6 main error categories and specific context schemas. This approach simplifies error handling while maintaining rich context and resolution options.

Error Categories:

• INVENTORY_ISSUE: Stock, availability, back-orders, discontinued items
• PRICING_ERROR: Price changes, discounts, tax calculation, currency issues
• SHIPPING_ERROR: Address validation, delivery restrictions, shipping zones, billing address requirements
• PAYMENT_ERROR: Payment limits, currency support, processor issues
• DATA_ERROR: Field validation, format issues, required fields
• BUSINESS_RULE_ERROR: Account restrictions, compliance, regional limits

Example - PO Box Shipping Restriction:

{
  "code": "SHIPPING_ERROR",
  "type": "INVALID_DATA",
  "message": "Shipping address validation failed",
  "user_message": "We can't ship to PO Box addresses. Please use a street address.",
  "field": "shipping_address",
  "context": {
    "specific_issue": "SHIPPING_TO_PO_BOX_NOT_ALLOWED",
    "po_box_detected": true,
    "restricted_items": ["LARGE-FURNITURE-001"],
    "restriction_reason": "oversized_item"
  },
  "resolution_options": [
    {
      "action": "UPDATE_ADDRESS",
      "label": "Use street address instead of PO Box",
      "metadata": {
        "priority": "high",
        "auto_applicable": false
      }
    }
  ]
}

Example - Price Change:

{
  "code": "PRICING_ERROR", 
  "type": "BUSINESS_RULE",
  "message": "Product pricing issue",
  "user_message": "The price for Ocean Blue T-Shirt has increased from $29.99 to $34.99. Continue with new price?",
  "variant_id": "SHIRT-OCEAN-BLUE",
  "context": {
    "specific_issue": "PRICE_MISMATCH",
    "variant_id": "SHIRT-OCEAN-BLUE",
    "original_price": "29.99",
    "current_price": "34.99",
    "currency_code": "USD",
    "price_change_reason": "promotional_ended",
    "price_increase": "5.00"
  },
  "resolution_options": [
    {
      "action": "ACCEPT_NEW_PRICE",
      "label": "Continue with $34.99",
      "metadata": {
        "cost_impact": "+$5.00",
        "priority": "HIGH",
        "auto_applicable": false
      }
    }
  ]
}

Example - Address Validation:

{
  "code": "SHIPPING_ERROR",
  "type": "INVALID_DATA",
  "message": "Shipping address validation failed",
  "user_message": "The shipping address appears to be incomplete. Please check and correct.",
  "field": "shipping_address.postal_code",
  "context": {
    "specific_issue": "SHIPPING_ADDRESS_INVALID",
    "validation_failures": ["invalid_postal_code"],
    "suggested_corrections": {
      "postal_code": "90210"
    },
    "address_quality_score": 0.3
  },
  "resolution_options": [
    {
      "action": "UPDATE_ADDRESS",
      "label": "Use suggested corrections",
      "metadata": {
        "priority": "HIGH",
        "auto_applicable": true
      }
    }
  ]
}

Example - Billing Address for Tax Calculation:

{
  "code": "DATA_ERROR",
  "type": "MISSING_FIELD", 
  "message": "Billing address needed for tax calculation",
  "user_message": "We need your billing address to calculate the correct sales tax for your order.",
  "field": "billing_address",
  "context": {
    "specific_issue": "BILLING_ADDRESS_FOR_TAX",
    "tax_jurisdiction_required": true,
    "current_tax_rate": "unknown",
    "supported_tax_regions": ["US", "CA", "EU"]
  },
  "resolution_options": [
    {
      "action": "PROVIDE_MISSING_FIELD",
      "label": "Add billing address",
      "metadata": {
        "priority": "MEDIUM",
        "auto_applicable": false
      }
    },
    {
      "action": "USE_SHIPPING_AS_BILLING",
      "label": "Same as shipping address",
      "metadata": {
        "priority": "HIGH", 
        "auto_applicable": true
      }
    }
  ]
}