Problem/Motivation

Commerce 3.x supports Drupal ^10.3 || ^11. A new major, 4.x, is needed to support Drupal 12, drop Drupal 10, and remove code deprecated for removal in 4.0.0.

3.x remains supported for Drupal 10/11 sites. 4.x supports Drupal ^11.5 || ^12, so sites can upgrade Commerce on Drupal 11 first and move to Drupal 12 afterwards.

The minimum was raised from 11.1 to 11.5 in #3638820, since fixing Drupal 12 deprecations requires APIs introduced in 11.5.

Proposed resolution

Do the work in small, independently committable child issues listed below. This issue only tracks them.

Annotations vs attributes

  • Every Commerce plugin type already provides an attribute class (since 3.x). This satisfies the Drupal 12 requirement that plugin types support attributes (change record).
  • Annotated plugins (payment gateways, checkout panes, promotion offers, conditions, etc.) remain supported in 4.x, since Drupal core keeps annotation discovery until Drupal 13. Contrib modules should convert their plugins to attributes; this works on Commerce 3.x and 4.x alike.
  • The Commerce plugin annotation classes will be deprecated in 4.x, and support for annotated Commerce plugins will be removed in 5.x.
  • Commerce's own entity types will be converted to attributes. Entity type attributes require Drupal 11.1, which the 4.x minimum covers.

Remaining tasks

Must have

Nice to have

4.x minor: B2B organization

Additive organization plumbing for B2B modules (commerce_b2b) to build on, using the 4.0 seams and organization API above. Child issues to be created; details are not final.

  • Organization on orders and carts: organization_id order field (present once an organization entity type exists), one cart per user per organization, organization set on order assignment
  • Order ownership by uid only for orders without an organization
  • Carts: CartProvider scopes every lookup (getCart(), getCartId(), getCarts(), getCartIds()) to the organization resolved for the account and store it already receives, so the organization switcher changes which carts are returned and the cart cache context follows. CartProviderInterface keeps its signatures (no organization parameter: NULL would mean both "resolve it" and "personal cart"); code needing another organization's cart creates the order and calls setOrganization().
  • The organization_id field on organization-owned entities (OrganizationOwnedInterface / OrganizationOwnedTrait ship in 4.0.0, #3639236: Add OrganizationInterface and an optional organization on the Context): commerce adds an organization_id base field to every entity type implementing the interface (orders first; payment methods, invoices and subscriptions when their modules support organizations), targeting the site's organization entity type. Includes an install routine for when that type appears after install, and a guard that skips entity types already defining an organization_id. OrganizationEntityTypeRepository lives in commerce.
  • Order organization condition (is one of / is not one of)

The default organization entity type (commerce_organization) ships as an optional Commerce submodule: a minimal reference entity, so the plumbing is tested in core. Group sites use a bridge instead and do not install it.

No release containing the organization plumbing is tagged until commerce_b2b exercises it (memberships, resolver, access grants).

User interface changes

None expected.

API changes

Removal of deprecated code; see child issues. Annotated plugins keep working.

Code checking $cart->access('update') for customers moves to the new update_cart operation. Classes that built a Context with new Context() get the context services injected. AddressBookInterface implementations take the optional Context argument. Sites relying on Commerce to pull in Inline Entity Form must require it themselves. Context gains an optional organization, with OrganizationInterface and resolver interfaces for B2B modules to implement. OrderInterface extends the new OrganizationOwnedInterface (getOrganization(), getOrganizationId(), setOrganization()), so a custom class implementing OrderInterface without extending Order must add them (OrganizationOwnedTrait provides them).

Data model changes

None expected in 4.0. The organization plumbing (4.x minor) adds an organization_id field to entity types implementing OrganizationOwnedInterface (orders first), present once an organization entity type exists.

Features for consideration

Comments

jsacksick created an issue. See original summary.

jsacksick’s picture

jsacksick’s picture

jsacksick’s picture

Issue summary: View changes
jsacksick’s picture

Issue summary: View changes
jsacksick’s picture

Issue summary: View changes

Updated the summary: 4.x requires Drupal ^11.5 since #3638820 was merged.

jsacksick’s picture

Actually... Realized now might be the time to drop the Inline entity form dependency since Commerce no longer depends on IEF anymore... And we couldn't really remove the dependency on Commerce 3.

jsacksick’s picture

Issue summary: View changes
jsacksick’s picture

Issue summary: View changes
jsacksick’s picture

Issue summary: View changes
jsacksick’s picture

Issue summary: View changes
rszrama’s picture

Noted today that we need to pick one of...

  1. Use organization_id fields on all entity types that should be owned by an organization.
  2. Use a field but with a namespaced name, like commerce_organization_id or commerce_org_id.
  3. Use an ownership entity model similar to Group, e.g., CommerceOrganizationContent or CommerceOrganizationRelationship, and risk reimplementing half of Group in Commerce Core. 🫠
rszrama’s picture

Issue summary: View changes
jsacksick’s picture

Issue summary: View changes

We're going with option 1, done generically. An entity owned by an organization carries organization_id, like uid for user ownership, behind a new OrganizationOwnedInterface / OrganizationOwnedTrait in commerce (next to OrganizationInterface). commerce's hook_entity_base_field_info() adds the field to every entity type whose class implements the interface, targeting the site's organization entity type, and only when there is one. Orders come first; payment methods, invoices and subscriptions follow when their modules support organizations. Entity types Commerce doesn't own get the field from the module that needs it (commerce_b2b adds it to profiles for the organization address book), with no class swap.

No prefix on Commerce's own entity types: it would break the store_id / order_id convention. Field UI fields can't collide (they're field_…), and for custom base fields the hook and install routine skip any entity type that already has an organization_id and report it in the status report. Entity types Commerce doesn't own (user, node) get a commerce_ prefix, like commerce_remote_id on users.

Option 3 would mean rebuilding Group, and every access check and listing would pay for a join. The one many-to-many relationship, user ↔ organization with roles, is commerce_b2b's membership entity.

This stays a 4.x minor rather than 4.0.0. The parts that need a major are already 4.0.0 must-haves (#3639236: Add OrganizationInterface and an optional organization on the Context, #3639232: Add context services to build the pricing Context, #3639234: Add checkout and update_cart order operations, #3639235: Pass an optional Context to the address book). What's left is additive: without an organization entity type there's no field, and with one, existing orders have an empty value, so uid ownership, carts and checkout don't change until an organization module sets it. Keeping it out of 4.0.0 means Drupal 12 support doesn't wait on commerce_b2b.

Issue summary updated accordingly.

jsacksick’s picture

Issue summary: View changes

OrganizationOwnedInterface / OrganizationOwnedTrait move to 4.0.0 in #3639236: Add OrganizationInterface and an optional organization on the Context: OrderInterface gains their methods, which is cleaner in a major. Until the 4.x minor adds the organization_id field, getOrganization() returns NULL. Summary updated.

jsacksick’s picture

Issue summary: View changes

Summary: documented how carts get scoped by organization in the 4.x minor. CartProviderInterface keeps its signatures, which is what lets this stay out of 4.0.0.

jsacksick’s picture

Issue summary: View changes