← All Articles

UCP Totals Contract Formalization: How Order Sums Really Work

UCP Schema Commerce

March 17, 2026 · PR #261 · Ilya Grigorik

About the Author

Ilya Grigorik is a Principal Engineer at Google and the primary architect of the Universal Commerce Protocol. Previously at Shopify, he's spent his career at the intersection of web performance, protocols, and commerce infrastructure. He's the author of "High Performance Browser Networking" and maintains an extensive track record in open standards work.

Why This Matters

When an AI agent displays an order total to a user, where does that number come from? The answer seems obvious—sum up line items, add taxes, subtract discounts. But in agentic commerce, the calculation path matters as much as the result. Businesses need to know agents aren't fabricating totals, and agents need to know which fields to trust.

PR #261 formalizes the totals contract: explicit definitions for what subtotal, total, and grand_total mean, how they relate to each other, and what validation rules apply.

What Changed

The PR introduces several key changes to UCP's order schema:

1. Explicit Field Definitions

Each totals field now has precise semantics:

subtotal: Sum of line item amounts before adjustments (taxes, discounts, shipping). This is the "list price" total.
total: The amount due after all adjustments except promotions that apply at payment time.
grand_total: The final amount to be collected, including all adjustments and payment-time promotions.

2. Calculation Relationships

The schema now documents how these fields relate:

subtotal + taxes - discounts + shipping + fees = total
total - payment_promotions = grand_total

This isn't just documentation—it enables validation. An agent can verify that the numbers are internally consistent before presenting them to users.

3. Required vs. Optional Fields

The PR clarifies which fields are required in different contexts:

grand_total is always required when presenting payment information
subtotal is required when line items are present
Breakdown fields (taxes, shipping, etc.) are optional but recommended for transparency

💡 Design Philosophy

The contract is explicit about one thing: the business is authoritative. An agent may calculate expected totals for validation, but the displayed totals must come from the business response. This prevents price discrepancies from confusing users when agent math doesn't match backend logic.

Technical Details

The PR modifies several schema files to implement the formalized contract:

// Order totals with explicit semantics
message OrderTotals {
  // Sum of line_items[].amount before adjustments
  // REQUIRED when line_items present
  Money subtotal = 1;
  
  // Pre-payment total after taxes, discounts, shipping, fees
  // subtotal + taxes - discounts + shipping + fees
  Money total = 2;
  
  // Final collection amount after payment-time adjustments
  // REQUIRED for checkout
  Money grand_total = 3;
  
  // Optional breakdown for transparency
  Money taxes = 10;
  Money discounts = 11;
  Money shipping = 12;
  Money fees = 13;
}

The schema also adds validation annotations that tooling can use to verify consistency:

option (ucp.validation) = {
  rule: "subtotal_consistency"
  message: "subtotal must equal sum of line_items[].amount"
};

Implications for Implementers

For AI Platforms

Agents should validate totals consistency when receiving order responses. If the math doesn't add up, that's a signal something is wrong—either a bug in the business implementation or a tampered response.

For Businesses

The formalized contract means businesses must be explicit about their pricing logic. If you have unusual fee structures or conditional discounts, they need to fit within this model. The schema is flexible enough to handle most cases, but edge cases may require documentation in the fees or discounts breakdown.

For Verification Tools

The explicit relationships enable automated verification. A compliance tool can now check that UCP responses are internally consistent without understanding business-specific pricing rules.

What's Next

This PR lands alongside #267 (disclosure contracts) as part of a larger push to formalize UCP's core contracts before 1.0. Expect similar treatment for:

Shipping cost calculations and delivery promise contracts
Tax jurisdiction handling and display requirements
Refund and return amount calculations

The protocol is moving from "flexible and loose" to "explicit and verifiable"—essential infrastructure for enterprise adoption where audit trails and compliance matter.