feat: Add Payment Terms with Well-Defined Schedules - #602
Draft
raginpirate wants to merge 3 commits into
Draft
Conversation
…entages with totals, improve documentation Assisted-By: devx/cda4fcd3-f600-4f4b-9e5e-884732556852
drewolson-google
left a comment
drewolson-google
left a comment
Collaborator
There was a problem hiding this comment.
A few small notes. Leaving a larger comment on #603.
| An `immediate` schedule **MUST** omit `due_at`; a `deferred` schedule **MUST** | ||
| include a non-empty `due_at`. The shared Schedule fields are: | ||
|
|
||
| * `anchor_date` — RFC 3339 reference point. If omitted, the anchor is the |
Collaborator
There was a problem hiding this comment.
the anchor is the instant successful checkout completion creates the order.
This reads weirdly.
|
|
||
| * `anchor_date` — RFC 3339 reference point. If omitted, the anchor is the | ||
| instant successful checkout completion creates the order. | ||
| * `offset` — ISO 8601 duration from the anchor to the first occurrence. |
Collaborator
There was a problem hiding this comment.
I'd suggest consistently using anchor_date if that's the name of the field.
archrao
reviewed
Aug 7, 2026
|
|
||
| Each payment schedule has `totals[]`. For a recurring schedule, those totals | ||
| apply to each occurrence. Expanding every occurrence, the sum of schedule | ||
| `total` entries **MUST** equal the checkout `total` exactly once. |
There was a problem hiding this comment.
In case of uneven totals due to 'occurrences' ie 100 split into 3. Should the merchant send multiple schedules so the totals adds up?
archrao
reviewed
Aug 7, 2026
| "payment": { | ||
| "type": "object", | ||
| "properties": { | ||
| "terms": { |
There was a problem hiding this comment.
Should we add minItems: 1 maxItem:1 as we mention order.payment.terms[] containing exactly one complete snapshot
archrao
reviewed
Aug 8, 2026
| { | ||
| "$schema": "https://json-schema.org/draft/2020-12/schema", | ||
| "$id": "https://ucp.dev/schemas/shopping/types/payment_term.json", | ||
| "title": "Payment Term", |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
7 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Introduces dev.ucp.shopping.payment_terms, an extension for expressing checkout-wide payment terms composed of immediate, deferred, or finite recurring payment schedules.
Businesses advertise complete terms through payment.available_terms[], including schedule timing and totals. Buyers select and fund a term directly through payment.instruments[].term_refs, which can target the whole term or individual schedules. This naturally composes with Split Payments—for example, using a gift card for an immediate deposit and a card for a deferred balance.
The resulting Order snapshots the complete accepted term under order.payment.terms[]. The model is designed to compose with the read-only Order payment instruments proposed in #584, preserving schedule assignments without carrying checkout-time credentials or handler details.
The structured schedule model gives platforms and businesses a shared way to determine:
Category (Required)
Please select one or more categories that apply to this change.
ucp-schematool (resolver, linter, validator). (Requires Maintainer approval)Related Issues
Checklist
!for breaking changes).Screenshots / Logs (if applicable)