[v4 beta][plugin-ecommerce] Guest cart merge ignores the configured cartItemMatcher

[alekseykurylev]

Configure a custom cart item field via cartsCollectionOverride and include it in carts.cartItemMatcher. Put the same product and variant in an existing account cart and a guest cart, with different values for that field. Then sign in as the account owner.

Expected: Two separate line items, each retaining its custom field value.
Actual: One line item with the combined quantity and the account cart's field value.

Reproduced with @payloadcms/plugin-ecommerce@4.0.0-beta.7. In createCartsCollection, addItemEndpoint receives cartItemMatcher, but mergeCartEndpoint does not. The merge endpoint already accepts the matcher, so the proposed fix is to pass it during registration.

[Medamineelkhattabi]

Your reading is right for beta.7, and main still has the same line. In createCartsCollection.ts only addItemEndpoint gets cartItemMatcher. mergeCartEndpoint({ cartsSlug }) gets none, so the merge operation falls back to defaultMergeItemMatcher, which compares product and variant IDs only.

The comment above that line hints at why it was left out: the types don't line up. CartItemMatcher takes newItem: NewCartItem, where product/variant are plain IDs, while the merge matcher takes newItem: CartItemData, where they can be populated docs. Passing the plugin matcher straight through doesn't type-check, so the fix needs a cast or a wider matcher type.

At runtime it's safe. mergeCart loads both carts with depth: 0 (L104-L130), so sourceItem.product and .variant are IDs, which is what your matcher already expects. When nothing matches, the guest item is pushed with all its fields except the row id (L162-L167), so your custom field is kept.

Until it's fixed you can't swap the endpoint through cartsCollectionOverride without copying the whole operation, because neither mergeCart nor mergeCartEndpoint is exported. The smallest workaround is patching the built file:

pnpm patch @payloadcms/plugin-ecommerce@4.0.0-beta.7

In dist/collections/carts/createCartsCollection.js, cartItemMatcher is already in scope (it's passed to addItemEndpoint a few lines above):

             mergeCartEndpoint({
+                cartItemMatcher,
                 cartsSlug
             }),

Then run pnpm patch-commit with the path pnpm printed, and drop the patch once a release includes the fix.