Skip to content

CAP-COM-ORD-001Build a buyer’s cart

Markdown

CAP-COM-ORD-001

Build a buyer’s cart

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationObserved

KindCapabilityProduct areaCommerceModuleCustomer purchases, purchased benefits and vendor stockRevision1

Read atservices-commerce c8b66a98react-console baf6dae3

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes
The cart identifies buying, acting, billing and receiving parties and validates the intended items.Unfinished carts close and release their outstanding holds.
Surfaces
consoleapijob
Intent sources
services-commerce:docs/milestones/plans/COMM-M2-plan.md#2. Scopeservices-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D8services-commerce:docs/milestones/plans/COMM-M2-plan.md#D13services-commerce:docs/milestones/plans/COMM-M2-plan.md#A7services-commerce:docs/milestones/plans/COMM-M2-plan.md#A17

Controls

33 controls apply, from the corpus control catalogue.

TC-IAM-006 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-005 TC-AZ-006 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-TEN-004 TC-CRY-001 TC-CRY-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-DAT-004 TC-LOG-001 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-AVL-004 TC-MON-001 TC-MON-002 TC-MON-004 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-004 TC-PI-005 TC-PRV-001 TC-PRV-002

Permissions

KeyChecked atScope
commerce.checkouts.createapitenant
commerce.checkouts.readapitenant
commerce.checkouts.updateapitenant
commerce.orders.createservicetenant

Business Rules

14 rules, 14 to be proved before approval. A rule's product intent is derived from its origin: 14 confirmed by a product decision, the rest inheriting this capability's confirmed.

IdRuleKindEnforced atProvenance
01must prove
Confirmed
Portal buyers work with carts belonging to their contact or naming them as the acting contact; authorized console staff can work with any cart in the workspace.
no proof recorded yet
permissionapi, servicetest
services-commerce:modules/checkout/tests/e2e/checkouts.e2e.spec.js#refuses a member opening a checkout for another contact, 403
02must prove
Confirmed
Before an item is saved, validation reports all detected problems with sale availability, registered ownership, positive whole quantities and purchase limits, required item details, and supported currency.
no proof recorded yet
validationapi, servicetest
services-commerce:modules/checkout/tests/e2e/checkouts.e2e.spec.js#refuses a quantity past the product’s purchase limit: quantity_out_of_limits
03must prove
Confirmed
A cart requires record identifiers for its buyer, acting contact, bill-to party and item recipients, and rejects slugs with a field-specific error before writing.
no proof recorded yet
validationapitest
services-commerce:modules/checkout/tests/e2e/checkout-record-ids.e2e.spec.js#refuses a buyer that is a slug when the checkout is opened, 400 naming buyer_id, and writes nothing
04must prove
Confirmed
Organization purchases use product purchasing roles first, store roles next and an active affiliation otherwise; staff with order-placing authority can bypass that check for a named contact, with the override recorded.
✓ Authorized staff purchase for an organization using a named contact, with the override retained.✗ A portal buyer without the required organizational purchasing role receives a refusal.
no proof recorded yet
permissionservicetest
services-commerce:modules/checkout/tests/e2e/checkouts.e2e.spec.js#lets a console user with commerce.orders.create buy for the organization naming any acting contact, and audits the override
05must prove
Confirmed
Authorized staff can sell unpublished products and products outside the store assortment, while portal buyers receive an explanation and their cart remains unchanged.
no proof recorded yet
policyservicetest
services-commerce:modules/checkout/tests/e2e/checkout-public-sale.e2e.spec.js#lets a console user holding commerce.orders.create open a checkout with the draft product and add the one outside the assortment
06must prove
Confirmed
Changes to an open cart advance its version and record the acting identity in its history, including actions by Rhythm support.
no proof recorded yet
invariantservice, databasetest
services-commerce:modules/checkout/tests/e2e/checkouts.e2e.spec.js#adds after the last, changes the intent and clears what was advised, removes, each bumping the version
07must prove
Confirmed
Carts expire seven days after creation, and the minute sweep abandons expired open carts in bounded expiry order using a system action within each workspace.
no proof recorded yet
lifecycleservice, databasetest
services-commerce:modules/checkout/tests/integration/services/checkout/checkout-sweeper.integration.spec.js#abandoned each expired open checkout in its own tenant, with the system as the actor and expired as the reason
08must prove
Confirmed
Abandonment prevents further cart edits and releases item holds through the applications that own them.
no proof recorded yet
lifecycleservicetest
services-commerce:modules/checkout/tests/e2e/checkouts.e2e.spec.js#moves an open checkout to abandoned, after which it no longer changes (409 checkout_not_open)
09must prove
Confirmed
An application can reserve a scarce item before placement, refuse competing buyers or an excessive extension, and release the reservation when the item is removed.
no proof recorded yet
policyservicetest
services-commerce:modules/checkout/tests/e2e/holds-and-claims.e2e.spec.js#refuses another buyer the booth: 409 hold_unavailable with the participant’s reason, and their preview marks the item unavailable
10must prove
Confirmed
The reservation sweep marks an item stale when its hold expires and makes the reserved resource available again.
no proof recorded yet
lifecycleservicetest
services-commerce:modules/checkout/tests/e2e/holds-and-claims.e2e.spec.js#expires the ledger’s row, marks the item stale with hold_expired on the trail, and counts it
11must prove
Confirmed
A bundle child must refer to a parent already present in the cart, or validation rejects it.
no proof recorded yet
validationapi, servicetest
services-commerce:modules/checkout/tests/e2e/checkout-record-ids.e2e.spec.js#refuses an item whose parent_item_id names no item of the checkout, 400 envelope_invalid, and takes one that does (COM-ACC-0025)
12must prove
Confirmed
Process references can contain 500 characters on a cart, but application calls omit references exceeding the shared contract’s 128-character limit.
no proof recorded yet
validationapi, servicetest
services-commerce:modules/checkout/tests/e2e/checkouts.e2e.spec.js#refuses a process_ref of 501 characters on create, 400
13must prove
Confirmed
A shipping choice records the selected strategy, and clearing that choice removes it from the cart.
no proof recorded yet
policyservicetest
services-commerce:modules/checkout/tests/unit/checkout/shipping-choice.spec.js#writes null for a cleared choice, the property present so the update clears the column
14must prove
Confirmed
A cart can move from open to preparing, abandoned or cancelled, and from preparing back to open or onward to placed; terminal carts refuse further transitions, and placement requires an order link.
no proof recorded yet
lifecycleserviceobserved

Scenarios

IdGivenWhenThenProvenance
01An organization customer orders shirts for a colleague, with Pat as its acting contact.Staff create the organizational cart and select the colleague for shipping.The intended parties are recorded and the purchasing-role override appears in history.unknown
02An open cart remains unfinished until its expiry passes.Expiry processing selects it on a minute run.It becomes abandoned and releases its holds.test
services-commerce:modules/checkout/tests/integration/services/checkout/checkout-sweeper.integration.spec.js#abandoned each expired open checkout in its own tenant, with the system as the actor and expired as the reason

Edge Cases

IdGivenWhenThenProvenance
03An existing item recipient needs to be removed.Submit both recipient fields as null, then try only one null field.The paired nulls clear the recipient; a lone null is refused.test
services-commerce:modules/checkout/tests/e2e/checkout-record-ids.e2e.spec.js#clears the recipient of an item changed with both fields null, keeps it when neither is given, and refuses one null alone (COM-ACC-0018)

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.