Skip to content

docs(checkout): cross-link cart_id from Create Checkout#439

Open
matthutchinson wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
matthutchinson:docs-cart-id-checkout-extension
Open

docs(checkout): cross-link cart_id from Create Checkout#439
matthutchinson wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
matthutchinson:docs-cart-id-checkout-extension

Conversation

@matthutchinson
Copy link
Copy Markdown
Contributor

@matthutchinson matthutchinson commented May 15, 2026

What

Add a one-line cross-link from the Create Checkout section in checkout.md to the existing Cart-to-Checkout Conversion section in cart.md, so a reader on the checkout page can discover cart_id and the conversion contract.

Why

The cart capability extends create_checkout with a cart_id field (defined in cart.json#/$defs/checkout and covered in prose under Cart → Cart-to-Checkout Conversion). The cart page covers it well, but the checkout page has no signpost — a reader on /specification/checkout/#create-checkout cannot tell that this field exists or where to find it.

This adds a single discoverability hop. No content duplication.

Change

 ### Create Checkout

 ...
 **Recommendation**: To minimize discrepancies and a streamlined user experience,
 product data (price/title etc.) provided by the business through the feeds
 **SHOULD** match the actual attributes returned in the response.

+When the [Cart](cart.md) capability is negotiated, the request payload
+accepts an additional `cart_id` field for cart-to-checkout conversion. See
+[Cart → Cart-to-Checkout Conversion](cart.md#cart-to-checkout-conversion) for
+the field contract.
+
 {{ method_fields('create_checkout', 'rest.openapi.json', 'checkout') }}

Verification

Local mkdocs build --strict succeeds with no non-cairosvg warnings. The cross-link resolves to ../cart/#cart-to-checkout-conversion, which is a stable existing anchor.


image

The cart capability extends create_checkout with a cart_id field for
cart-to-checkout conversion (defined in cart.json #/$defs/checkout).
Today this is covered in prose on the cart page under
'Cart-to-Checkout Conversion', but a reader on the checkout page has
no way to discover it from the Create Checkout section.

Add a one-line cross-link under Create Checkout pointing to the
existing cart.md#cart-to-checkout-conversion section.
@matthutchinson matthutchinson force-pushed the docs-cart-id-checkout-extension branch from 9b2b471 to ea3bab5 Compare May 15, 2026 16:28
@matthutchinson matthutchinson changed the title docs(cart): render cart_id field on Create Checkout extension docs(checkout): cross-link cart_id from Create Checkout May 15, 2026
@damaz91
Copy link
Copy Markdown
Contributor

damaz91 commented May 19, 2026

While I see the value of this PR from a clarity standpoint, I also think we either do this for all extensions or not doing this at all. If we approve this PR we should also add a callout for every Checkout extension (Fulfillment, Discount, Buyer Consent, ..)

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants