Repository navigation
Description
Summary
Identity linking can say that sign-in would help (identity_optional), that sign-in is needed (identity_required) or that a scope is missing (insufficient_scope). It cannot say that the buyer is signed in but the business does not apply that account's terms yet. This proposal adds a small extension of Catalog. It defines two codes, account_pending and account_ineligible, and one Action type for a hosted step the buyer still has to finish. They describe the signed-in account and never a product.
The gap is not only B2B. Membership or trade pricing behind an approval may hit it too. The B2B charter (#947) lists "machine-readable buyer eligibility" in Phase 1, and this covers one part of that. I'd welcome review from the #947 authors. I won't ask for a TC vote until that council is seated and has looked at it, and I'm happy for it to move into the council's work.
Motivation
Some businesses decide per account whether to apply negotiated prices or terms. A person at the business may approve each new buyer, or the buyer may have to accept an agreement first. The spec treats this as runtime. Its B2B wholesaler example calls eligibility, pricing and payment terms "user attributes the merchant resolves at runtime, not additional scopes". But nothing tells the platform why a signed-in buyer still sees public terms. A buyer waiting for approval looks the same as one who will never qualify, or as a broken sign-in.
We run the Business side for a B2B software seller whose prices sit behind an NDA (see #1028). Until this week the NDA was accepted inside sign-in. With no code for "pending", we held sign-in open until a person at the seller approved the buyer, which hid that state from the platform. We have now moved that seller to the design below. No real buyer has linked through it yet.
Goals
- A platform can tell "waiting on the buyer", "waiting on the business" and "not eligible" apart, without parsing prose.
- Sign-in can finish before the business decides, and the platform can explain the wait.
- Nothing in the signal differs by product.
Non-Goals
- New scopes, or changes to the OAuth flow or to
401and403handling. - Price states for variants, which are [Proposal]: Caller-dependent catalog pricing states for price-on-request #969 and feat!: prototype conditional Catalog pricing states for #969 #1042.
- Quote lifecycle ([Proposal]: Quote extension — Business-authoritative quotation binding on Cart and Checkout #929), the buying organization's own approvals, and how a user maps to a buying organization ([DTC Charter]: B2B Procurement #947).
- Buyer-asserted
context.eligibilityclaims, which stay as they are. - Cart and Checkout, until someone implements them. That includes terms that change during a checkout.
Detailed Design
-
Extension.
dev.ucp.shopping.account_statusextendsdev.ucp.shopping.catalog.searchanddev.ucp.shopping.catalog.lookup. UCP has no way for one extension to require another, so the business treats this extension as inactive unlessdev.ucp.common.identity_linkingis also in the negotiated intersection. A business adopts it when it applies terms per account, for example negotiated prices behind an approval or an agreement. Here "account" is what the business applies terms to for this token: the signed-in user, or a buying organization the business links that user to. If one token maps to several buying organizations, which one applies is left to [DTC Charter]: B2B Procurement #947. -
Account status codes. On a capability where the extension is active, when a request carries a valid user identity token, the business MUST include exactly one of these
infocodes on every successful response while that state holds, whatever the response contains:account_pending: the business has not applied this account's terms yet.account_ineligible: the business does not apply account terms to this account. This holds until the business changes its decision. It is not permanent.
On a request with a valid token, a response with no account code means the account's terms apply. So the business MUST NOT fail open. If it cannot tell the account's state, it sends
account_pendingor an error. If it rejects the token, it MUST answer401withidentity_required, as for a gated operation (see docs(identity-linking): say how a business answers a token it rejects on an ungated operation #1044). A business SHOULD NOT sendidentity_optionalfor the same reason as one of these codes. -
Outstanding step. When the buyer must finish a hosted step before account terms apply, such as accepting an agreement, the business MUST include an Action of type
dev.ucp.shopping.account_status.stepwithconfig.urlset to that step. Theaccount_pendingmessage'spathMUST point to it. When several steps are outstanding, the business includes all of them, as for every Action, in the order the buyer should finish them.pathpoints to the first. A step that can only start after another is done is not outstanding yet. The step is for the person, so the platform handsconfig.urlto the buyer. The effect this Action gates is the account's terms.config.urlMUST NOT differ by product, and the business MUST NOT use it to carry an OAuth authorization request, the same rule as forcontinue_url. A step can also come after approval, for example a renewed agreement. The account is then pending again until the step is done. -
continue_urlor step. A business usescontinue_urlon the401when the step must happen before it issues a token. It uses thestepAction when the buyer already holds a valid token. -
Privacy. While an account is pending or ineligible, the business MUST show each variant as it would without this account's terms. Buyer-asserted
context.eligibilitybenefits still apply. That covers every per-product field and message. If feat!: prototype conditional Catalog pricing states for #969 #1042 lands, a variant in itsundisclosedstate staysundisclosed. The codes, theircontentand the Action MUST NOT differ by product. So they tell the token holder about its own account, and nothing about which products carry account prices.
What a platform does in each state, with the extension active:
| State | Signal | Platform |
|---|---|---|
| Waiting on the buyer | account_pending with a step Action |
Hand the step to the buyer, then repeat the request |
| Waiting on the business | account_pending, no Action |
Explain the wait and repeat later. This version gives no retry time |
| Not eligible | account_ineligible |
Don't restart sign-in for this account. The decision can change later |
| Approved | No account code | The terms shown are the account's terms |
Example, from our seller's reply to a catalog search by a signed-in buyer who has not accepted the NDA yet. The extension and Action carry this proposal's names. Hosts and ids are placeholders, and per-product messages are cut:
{
"ucp": {
"version": "2026-08-25",
"capabilities": {
"dev.ucp.shopping.catalog.search": [{ "version": "2026-08-25" }],
"dev.ucp.common.identity_linking": [{ "version": "2026-08-25" }],
"dev.ucp.shopping.account_status": [{ "version": "<draft>" }]
}
},
"products": [{ "id": "<product>", "variants": [{ "id": "<variant>" }] }],
"actions": {
"dev.ucp.shopping.account_status.step": [
{ "id": "nda", "config": { "url": "https://business.example.com/nda/account" } }
]
},
"messages": [{
"type": "info", "code": "account_pending",
"content": "Accept the seller's NDA to finish setting up this account. Prices appear after the seller approves it.",
"path": "$.actions['dev.ucp.shopping.account_status.step'][0]"
}]
}Once the buyer accepts, the same call returns account_pending with no Action and no path. Once a person at the seller approves, it returns no account code and the account's prices.
Cart and Checkout, next. This version is Catalog only, because no one runs Cart or Checkout with it yet. A pending buyer can still check out at the terms shown, and nothing warns them. The intended next version extends Cart and Checkout too, and sends the same code there as a warning, so the buyer knows the totals use the terms shown. It would also need a rule for terms that change during a checkout. It waits for a business that implements it.
Risks and Mitigations
- The response shapes don't change. A platform that ignores the codes may still see something new. A business that adopts them can finish sign-in earlier, so a platform can now hold a valid token and see public terms with no explanation it understands.
- Identity linking cannot hold this alone. It extends nothing, and an Action needs a declaring extension that is active for the capability. We are glad to move the rules into identity linking's text, with a thin extension that only declares the Action, if maintainers prefer.
- A signal that stops before checkout may not be enough for procurement platforms. See "Cart and Checkout, next".
- The codes sit next to the
eligibility_*claim codes. Theaccount_prefix keeps a business decision apart from a buyer claim, and the names are open. - Phase 1 of [DTC Charter]: B2B Procurement #947 may want more: reasons, a retry time, a signal that the step is done, or a push when approval lands. This proposal keeps to the smallest signal, and it can grow there.
Test Plan
- Schema examples for both codes and the Action, checked by the repo's example validation.
- Conformance cases under the framework in feat: add the vertical-agnostic conformance framework and runner (RFC #520, 1/3) conformance#120, gated by capability: a test account in each state, the code on every response including one with no products, and the Action present and then gone after the step.
- Switched on for our NDA-gated seller on 5 November 2026, catalog only, because our server has no cart or checkout. Sign-in ends after an emailed code, the NDA is a step, and a person at the seller approves each account. A daily check, added the same day, moves one test account through all four states and checks every response, including a lookup that returns no products. Our server still uses draft names,
dev.ucp.common.identity_linking.account_stepunder a draft identity-linking version. It will move to this proposal's names.
Graduation Criteria
- At least two businesses implement the codes, one of them not run by us, and one platform acts on them.
- The conformance cases are merged.
Implementation History
- Implementer notes: buyer eligibility for NDA-only B2B prices through identity linking #1028: implementer notes on NDA-gated prices through identity linking, questions 1 and 2.
- [Proposal]: Caller-dependent catalog pricing states for price-on-request #969 and feat!: prototype conditional Catalog pricing states for #969 #1042: price states. That work says what a variant shows, and this says why an account sees it.
- docs(identity-linking): say how a business answers a token it rejects on an ungated operation #1044: what a business returns for a token it rejects on an ungated operation.
- [Proposal]: Corporate negotiated-rate entitlement for lodging #991: corporate negotiated-rate entitlement for lodging. It asks where entitlement is checked. This proposal covers the next question, how a business says the check is still pending.
Code of Conduct
- I agree to follow this project's Code of Conduct
🤖 Drafted with Claude Code. I checked it against the spec, and our seller runs it.
Activity
feat(catalog): account status extension (Universal-Commerce-Protocol#…
evoleinik commentedon Nov 8, 2026
Draft implementation: #1059.
feat(catalog): account status extension (Universal-Commerce-Protocol#…