feat(schema): add buyer_notes field to line items

[hemanth]

Summary

Adds an optional buyer_notes string field to both line_item and order_line_item schemas, enabling per-item buyer instructions.

Closes #349

Motivation

Line items currently have no field for buyer-specific instructions. This is a gap for common commerce scenarios:

• Food ordering: "no onions", "extra sauce on the side"
• Gift purchases: "gift wrap, include card: Happy Birthday!"
• Custom products: "engrave: J.D. 2026"
• Delivery instructions: "leave at back door" (per-item, not per-order)

Voice and chat agents especially need this — they naturally collect customization preferences during conversation, but have no structured field to pass them through.

Changes

source/schemas/shopping/types/line_item.json

• Added buyer_notes (string, maxLength 500)
• ucp_request: optional on create and update
• Business MAY act on, echo back, or ignore

source/schemas/shopping/types/order_line_item.json

• Added buyer_notes (string, maxLength 500, read-only)
• Preserved from checkout into the order record
• Business SHOULD surface in fulfillment workflows

Design decisions

Decision	Rationale
Single string vs structured object	Keeps it simple. Structured customization (modifiers, add-ons) belongs in the catalog/item model, not in free-text notes.
maxLength: 500	Enough for meaningful instructions, prevents abuse. Businesses MAY enforce shorter limits.
Optional, not required	Zero breaking changes. Businesses that do not support buyer notes simply ignore the field.
On line_item (not checkout)	Notes are per-item, not per-order. A buyer might want different instructions for different items.
Preserved on order_line_item	Fulfillment teams need to see buyer instructions. Dropping them at order creation would defeat the purpose.

Example

{
  "line_items": [
    {
      "item": { "id": "variant_latte_lg", "title": "Large Oat Latte" },
      "quantity": 1,
      "buyer_notes": "Extra hot, oat milk, no foam"
    },
    {
      "item": { "id": "variant_croissant", "title": "Butter Croissant" },
      "quantity": 2,
      "buyer_notes": "Warm please"
    }
  ]
}

Backward compatibility

Fully backward-compatible. The field is optional on all operations. Existing implementations that do not send or handle buyer_notes are unaffected.

[damaz91]

Thanks for contributing to UCP. The concept of buyer provided notes will be made possible by the work in #481

I'm closing this out. Please feel free to re-open if you think #481 does not capture the full intent of this PR.

[hemanth]

Thanks @damaz91 for pointing to #481 — the Additional Fields proposal is great work. After reviewing it though, I think the two PRs are complementary rather than overlapping.

Additional Fields (#481) solves business-defined, checkout-scoped data collection — the business declares structured fields (PO numbers, delivery date pickers, age acknowledgements) and the platform collects values at checkout. That's a different problem from what #402 addresses.

buyer_notes (#402) solves buyer-initiated, per-line-item instructions — free-text that the buyer attaches to individual items. The key differences:

	buyer_notes (#402)	Additional Fields (#481)
Scope	Per line item	Per checkout
Who defines it	Buyer provides ad-hoc	Business pre-declares fields
Schema	Simple string on line_item	Full extension with typed inputs + config negotiation
Example	"Extra hot, no foam" on the latte	"PO number: ABC-123" on the order

A voice agent saying "The latte — extra hot, no foam. The croissant — warm please." produces two different notes on two different line items. Additional Fields has no line-item scoping, so there's no way to express this with #481 alone.

Happy to re-open this if you agree they're complementary, or if you'd prefer, I can propose buyer_notes as a line-item-scoped type within the Additional Fields framework. Let me know what makes sense.

[damaz91]

Thanks for noting this @hemanth - I think it would make sense to see if the scope of this PR can be included in #481 - can you try? If it turns out that lineitem-level buyer_notes can't be accomplished there, feel free to reopen this.

Thanks!