Skip to content

feat: Add ec.totals.change to Embedded Checkout Protocol#272

Open
lemonmade wants to merge 2 commits intomainfrom
add-totals-change-message
Open

feat: Add ec.totals.change to Embedded Checkout Protocol#272
lemonmade wants to merge 2 commits intomainfrom
add-totals-change-message

Conversation

@lemonmade
Copy link
Contributor

Description

This PR adds an ec.totals.change message to the Embedded Checkout Protocol. This message allows hosts to be informed of changes to the checkout state that do not have an accompanying ec.{domain}.change event today, like taxes and fees, which are entirely contained in totals. It also allows hosts to be informed of totals-only changes that may result from asynchronous updates after a domain event, such as potentially-slow shipping rate updates after a ec.fulfillment.change message has indicated the initial application of the change.

Type of change

Please delete options that are not relevant.

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing
    functionality to not work as expected, including removal of schema files
    or fields
    )
  • Documentation update

Checklist

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • Any dependent changes have been merged and published in downstream modules

@lemonmade lemonmade requested review from a team as code owners March 18, 2026 16:34
@lemonmade lemonmade added the TC review Ready for TC review label Mar 18, 2026
@lemonmade lemonmade added this to the 2026-01-23 milestone Mar 18, 2026
Copy link
Contributor

@westeezy westeezy left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this seems reasonable and appreciate the strict rule on ordering to keep it predictable.

Copy link
Contributor

@jingyli jingyli left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Change overall LGTM, just have a conceptual question regarding expectation when a domain-specific notification exists.

When a change also triggers a domain-specific message (e.g.,
`ec.line_items.change`, `ec.buyer.change`, or `ec.payment.change`), the business
**MUST** send the domain-specific message first, then follow it with
`ec.totals.change`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Naive QQ: I understand this is nice from a consistency perspective, but is there any additional benefits from mandating business to MUST send both notifications if the domain-specific message also has its own mandate to send the entire latest checkout state (which naturally encapsulates ec.totals.change)? It feels like we are going to be exchanging the same checkout object multiple times throughout the embedded checkout's lifecycle (especially if we are going to mirror this pattern for other EP bindings like Embedded Cart, where it's possible many line_item changes will occur).

Should we loosen the guideline to MAY (or SHOULD) or do the opposite where if a domain-specific message exist, then that must be the one message sent back to host with the updated totals?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We discussed this internally too, as were also a little worried by the amount of data flying over the wire for these changes. In the end, I think this contract is still right, though — it is weird for only some changes to totals to be communicated with this message, but not others, and I felt uncomfortable with the implementation instructions for both host and embedded checkout when I tried writing docs for a version that deduplicated ec.totals.change with other messages.

@lemonmade lemonmade force-pushed the add-totals-change-message branch from bdcef3d to 9f22986 Compare March 19, 2026 17:22
@mmohades
Copy link

Thanks for putting this together @lemonmade !! Beautifully done! :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

TC review Ready for TC review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants