Handling Complex Orders via UCP

Not all orders are simple single-item purchases. This guide covers how to handle complex order scenarios while maintaining smooth AI agent interactions.

Complex Order Types

Multi-Item Carts

{
  "cart": {
    "items": [
      {"product_id": "prod_a", "quantity": 2},
      {"product_id": "prod_b", "quantity": 1},
      {"product_id": "prod_c", "quantity": 3}
    ],
    "item_count": 6,
    "unique_items": 3
  }
}

Challenges:

• Mixed availability
• Multiple shipping options
• Complex pricing (bulk discounts)

Product Bundles

{
  "bundle": {
    "bundle_id": "bundle_starter_kit",
    "components": [
      {"product_id": "prod_main", "included": true},
      {"product_id": "prod_accessory_1", "included": true},
      {"product_id": "prod_accessory_2", "included": true}
    ],
    "bundle_price": 149.99,
    "savings": 30.00
  }
}

Challenges:

• Component availability
• Bundle-specific pricing
• Partial fulfillment rules

Subscriptions

{
  "subscription": {
    "product_id": "prod_coffee",
    "frequency": "monthly",
    "quantity": 2,
    "first_delivery": "2026-01-20",
    "commitment": "none",
    "price_per_delivery": 29.99
  }
}

Challenges:

• Recurring authorization
• Schedule management
• Cancellation policies

UCP Configuration for Complex Orders

Capability Declaration

{
  "capabilities": {
    "checkout": {
      "complex_orders": {
        "multi_item": true,
        "max_items": 50,
        "bundles_supported": true,
        "subscriptions_supported": true,
        "split_shipments": true
      }
    }
  }
}

Order Type Flags

Handling Split Shipments

When Items Ship Separately

{
  "shipments": [
    {
      "shipment_id": "ship_1",
      "items": ["item_a", "item_b"],
      "warehouse": "west_coast",
      "estimated_delivery": "2026-01-15"
    },
    {
      "shipment_id": "ship_2",
      "items": ["item_c"],
      "warehouse": "east_coast",
      "estimated_delivery": "2026-01-17"
    }
  ]
}

Agent Communication

Clearly communicate:

• Number of shipments
• Items per shipment
• Delivery dates
• Tracking numbers (when available)

Subscription Handling

Subscription Flow

1. Product Selection - Agent selects subscribable product
2. Frequency Choice - Weekly, monthly, quarterly
3. First Delivery - Schedule first shipment
4. Authorization - Payment method setup
5. Confirmation - Subscription activated

Escalation Triggers

Subscriptions typically require escalation for:

• First-time subscription setup
• Payment method authorization
• Terms acceptance

Subscription Management Endpoints

{
  "extensions": {
    "subscriptions": {
      "create": "/ucp/v1/subscriptions",
      "modify": "/ucp/v1/subscriptions/{id}",
      "pause": "/ucp/v1/subscriptions/{id}/pause",
      "cancel": "/ucp/v1/subscriptions/{id}/cancel"
    }
  }
}

Bundle Handling

Bundle Discovery

{
  "product": {
    "id": "bundle_gaming",
    "type": "bundle",
    "components": [
      {"id": "console", "name": "Gaming Console"},
      {"id": "controller", "name": "Extra Controller"},
      {"id": "game", "name": "Launch Title"}
    ],
    "bundle_only_items": ["controller"],
    "customizable": false
  }
}

Bundle Availability

Check all components:

async function checkBundleAvailability(bundle) {
  const componentAvailability = await Promise.all(
    bundle.components.map(c => checkInventory(c.id))
  );

  return componentAvailability.every(a => a.available);
}

Mixed Cart Handling

Cart with Mixed Types

{
  "cart": {
    "standard_items": [
      {"product_id": "prod_single", "type": "standard"}
    ],
    "bundle_items": [
      {"bundle_id": "bundle_kit", "type": "bundle"}
    ],
    "subscription_items": [
      {"product_id": "prod_subscribe", "type": "subscription"}
    ]
  }
}

Processing Order

1. Process standard items first
2. Validate bundle availability
3. Handle subscription setup (may escalate)
4. Calculate combined totals

Error Handling

Partial Availability

{
  "availability_check": {
    "fully_available": false,
    "available_items": ["item_a", "item_b"],
    "unavailable_items": [
      {
        "item_id": "item_c",
        "reason": "out_of_stock",
        "available_date": "2026-01-20"
      }
    ],
    "suggested_action": "proceed_partial"
  }
}

Agent Response Options

• Proceed with available items
• Wait for all items
• Cancel order
• Substitute unavailable items

Related Reading

• UCP Checkout State Machine
• UCP Extensions Guide
• UCP Operations Guide

---

Handle complex orders seamlessly with Noema's order management tools.

---

Want to see how your store scores? Run a free AI readiness scan and get your store's AI visibility report in 60 seconds.

---

About the Author: Josh is the founder of Noema, an AI commerce observability platform that helps e-commerce brands understand how AI shopping agents see their products. Noema has scanned 80,000+ Shopify stores to build the industry's most comprehensive AI readiness benchmarks.