Skip to content

docs(cart): define the continue_url destination and format - #801

Open
YanisMtcr wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
YanisMtcr:docs/cart-continue-url
Open

docs(cart): define the continue_url destination and format#801
YanisMtcr wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
YanisMtcr:docs/cart-continue-url

Conversation

@YanisMtcr

Copy link
Copy Markdown

Motivation

The cart page says businesses SHOULD provide continue_url, and the schema describes it as "URL for cart handoff and session recovery", but nothing says where the URL should lead or what it has to preserve. The requirements list still carries TODO: discuss continue_url destination - cart vs checkout from #73, where two readings met: for some implementers the URL is the checkout URL, for others the business decides the intended use (convert to checkout, or keep building the cart).

The checkout page answers the same questions for checkout in its Continue URL section (availability, format, server-side state or permalink); the cart page has no equivalent. And the permalink specification already lets a business merge items into an existing cart, create a new cart, or stage a checkout, so the destination question has an answer elsewhere in the spec: the business chooses.

This came up while implementing the cart capability: a cart session is served by the business's UCP endpoint, which does not always share state with the storefront, and a continue_url pointing at the storefront's own cart page lands the buyer on an empty basket.

What this PR changes

  • shopping/cart/index.md - adds a ## Continue URL section after Cart-to-Checkout Conversion. Destination: the business chooses (cart page, checkout entry, embedded flow); whatever it picks MUST present the cart's current line_items, quantities and selected variants included, without the buyer re-adding them; items no longer available follow the permalink redirect resolution rules. Format: absolute HTTPS URL that MUST carry or reference the cart contents, using either approach the checkout page already describes by reference (server-side cart state or a stateless permalink), rather than restating them.
  • Removes the TODO bullet and appends a link to the new section to the existing SHOULD bullet; the requirement level is unchanged.

Normative addition, scoped to the field: two MUSTs on continue_url (absolute HTTPS, contents preserved). Both mirror what the checkout page already requires for its own continue_url. No schema change.

Overlaps with nothing open: #740 (cart terminal status) edits the same requirements list but leaves this bullet as is, and #486 (return after handoff) is checkout-side.

Category (Required)

  • Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
  • Governance/Contributing: Updates to GOVERNANCE.md, CONTRIBUTING.md, or CODEOWNERS. (Requires Governance Council approval)
  • Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
  • Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
  • Infrastructure: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
  • Maintenance: Version bumps, lockfile updates, or minor bug fixes. (Requires DevOps Maintainer approval)
  • SDK: Language-specific SDK updates and releases. (Requires DevOps Maintainer approval)
  • Samples / Conformance: Maintaining samples and the conformance suite. (Requires Maintainer approval)
  • UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)
  • Community Health (.github): Updates to templates, workflows, or org-level configs. (Requires DevOps Maintainer approval)

Related Issues

None.

Checklist

  • I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
  • I have updated the documentation (if applicable).
  • My changes pass all local linting and formatting checks.
  • 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.
  • (For Core/Capability) I have included/updated the relevant JSON schemas.
  • I have regenerated Python Pydantic models by running generate_models.sh under python_sdk.

The cart page asks businesses to provide continue_url but leaves its destination as a TODO from Universal-Commerce-Protocol#73. The permalink spec already lets the business resolve into a cart or a checkout; this adds a Continue URL section that keeps that choice open, requires the cart contents to survive the handoff, and points at the checkout page for the format.
@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Sep 2, 2026
@carolinerg1 carolinerg1 added status:under-review gov:needs-gc-review and removed status:needs-triage Signal that the PR is ready for human triage labels Sep 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants