Skip to content

[Proposal]: Account status for signed-in buyers #1047

Open

Description

@evoleinik

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

Detailed Design

  1. Extension. dev.ucp.shopping.account_status extends dev.ucp.shopping.catalog.search and dev.ucp.shopping.catalog.lookup. UCP has no way for one extension to require another, so the business treats this extension as inactive unless dev.ucp.common.identity_linking is 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.

  2. 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 info codes 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_pending or an error. If it rejects the token, it MUST answer 401 with identity_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 send identity_optional for the same reason as one of these codes.

  3. 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.step with config.url set to that step. The account_pending message's path MUST 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. path points 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 hands config.url to the buyer. The effect this Action gates is the account's terms. config.url MUST NOT differ by product, and the business MUST NOT use it to carry an OAuth authorization request, the same rule as for continue_url. A step can also come after approval, for example a renewed agreement. The account is then pending again until the step is done.

  4. continue_url or step. A business uses continue_url on the 401 when the step must happen before it issues a token. It uses the step Action when the buyer already holds a valid token.

  5. 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.eligibility benefits still apply. That covers every per-product field and message. If feat!: prototype conditional Catalog pricing states for #969 #1042 lands, a variant in its undisclosed state stays undisclosed. The codes, their content and 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. The account_ 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_step under 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

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

  1. evoleinik commented on Nov 8, 2026

    @evoleinik
    Author

    Draft implementation: #1059.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions