feat: add ValidateCartMutation extension points by evander-corebiz · Pull Request #3441 · vtex/faststore

evander-corebiz · 2026-08-11T15:26:57Z

What's the purpose of this pull request?

FastStore's native ValidateCartMutation does not provide extension points for stores that need to expose additional data from the VTEX orderForm, such as custom item fields, cart totals, coupons, or totalizers.

This PR adds extension points for StoreOffer and StoreCart, allowing stores to include custom cart data while keeping FastStore's native cart reconciliation as the source of truth.

How it works?

ValidateCartMutation now includes two extension fragments:

CartItemAdditional for extending StoreOffer
StoreCartAdditional for extending StoreCart

Stores can extend the GraphQL schema and include their custom fields in these fragments.

Example:

extend type StoreOffer {
customLabel: String
}

extend type StoreCart {
total: Float
coupon: String
}

fragment CartItemAdditional on StoreOffer {
customLabel
}

fragment StoreCartAdditional on StoreCart {
total
coupon
}

Cart-level fields that depend on the VTEX orderForm can be resolved through StoreCartRoot:

import type { StoreCartRoot } from '@faststore/api'

export default {
StoreCart: {
total: (root: StoreCartRoot) => root.__orderForm.value / 100,
coupon: (root: StoreCartRoot) =>
root.__orderForm.marketingData?.coupon ?? null,
},
}

These additional fields are only exposed in the GraphQL response.

The existing cart reconciliation, item comparison, local cart handling, and orderForm update behavior remain unchanged.

How to test it?

Run code generation:

pnpm --filter @faststore/core generate

Run API integration tests:

pnpm --filter @faststore/api exec vitest run test/integration/schema.test.ts test/integration/mutations.test.ts

Run the Core test suite:

pnpm --filter @faststore/core test

Run Biome validation:

pnpm exec biome check packages/api/src/platforms/vtex/resolvers/root.ts packages/api/src/platforms/vtex/resolvers/validateCart.ts packages/core/src/sdk/cart/index.ts packages/core/src/customizations/src/fragments/ValidateCartMutation.ts packages/core/README.md

In a FastStore store:
Extend StoreOffer and/or StoreCart in src/graphql/vtex/typeDefs.
Add the custom fields to CartItemAdditional and/or StoreCartAdditional.
Add custom resolvers when the fields depend on the VTEX orderForm.
Execute ValidateCartMutation.
Confirm that native and custom cart fields are returned together.
Confirm that cart reconciliation still works when local cart data differs from the orderForm.

Starters Deploy Preview

Not available yet.

The feature can be tested using a FastStore store configured with this PR branch.

References

Extending the FastStore API schema](https://developers.vtex.com/docs/guides/faststore/api-extensions-extending-api-schema)
Extending FastStore queries using fragments](https://developers.vtex.com/docs/guides/faststore/api-extensions-extending-queries-using-fragments)
packages/core/src/sdk/cart/index.ts
packages/core/src/customizations/src/fragments/ValidateCartMutation.ts
packages/api/src/platforms/vtex/resolvers/validateCart.ts

Summary by CodeRabbit

New Features
- Added support for custom fields in cart validation results.
- Cart item customizations can now include offer quantity.
- Validated carts can expose the order number for downstream use.
- Integrations can access the original VTEX order details when resolving custom cart fields.
Documentation
- Added guidance and examples for configuring custom cart validation fields, fragments, and resolvers.

Summary by CodeRabbit

New Features
- Added support for custom fields on cart items and validated carts during cart validation.
- Cart validation now preserves configured additional cart fields, including order details.
- Reorder flows now consistently retain validated cart information.
Documentation
- Added guidance and examples for extending cart validation with custom GraphQL fields.
Tests
- Added coverage verifying custom cart fields are preserved correctly during validation.

coderabbitai · 2026-08-11T15:27:18Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 463fb024-452c-4832-b8ac-c48b8d327961

📥 Commits

Reviewing files that changed from the base of the PR and between 0c1fcca and 8d70424.

📒 Files selected for processing (3)

packages/core/src/sdk/account/useReorder.ts
packages/core/src/sdk/cart/index.ts
packages/core/test/sdk/cart/index.test.ts

Walkthrough

This PR exposes the source VTEX OrderForm to cart resolvers, adds custom ValidateCartMutation fragments, preserves additional cart fields, and reuses validated-cart conversion in reorder flows.

Changes

Cart validation extensions

Layer / File(s)	Summary
Order form resolver context `packages/api/src/platforms/vtex/resolvers/root.ts`, `packages/api/src/platforms/vtex/resolvers/validateCart.ts`	`orderFormToCart` attaches the source VTEX `OrderForm` as `__orderForm`. `StoreCartRoot` types this resolver context.
Validation fragment wiring `packages/core/src/customizations/src/fragments/ValidateCartMutation.ts`, `packages/core/src/sdk/cart/index.ts`, `packages/core/README.md`	The SDK requests additional cart and item fields. The exported fragments and documentation describe custom resolvers and access to `StoreCartRoot.__orderForm`.
Validated cart conversion and reuse `packages/core/src/sdk/cart/index.ts`, `packages/core/src/sdk/account/useReorder.ts`, `packages/core/test/sdk/cart/index.test.ts`	`getCartFromValidatedCart` preserves additional fields and maps validated data into the SDK cart shape. `validateCart` and `useReorder` use the shared helper. Tests cover returned fields and filtered variables.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant SDK
  participant GraphQL
  participant ValidateCartResolver
  participant VTEX
  SDK->>GraphQL: Request validation fragments
  GraphQL->>ValidateCartResolver: Execute ValidateCartMutation
  ValidateCartResolver->>VTEX: Convert OrderForm
  VTEX-->>ValidateCartResolver: Return OrderForm
  ValidateCartResolver-->>GraphQL: Return cart with custom fields
  GraphQL-->>SDK: Return validated cart
  SDK->>SDK: Map validated cart with getCartFromValidatedCart

Possibly related PRs

vtex/faststore#3220: Both PRs modify cart validation and StoreOffer/CartItem handling.
vtex/faststore#3435: Both PRs modify the validateCart flow, but this PR adds cart extension data.

Suggested labels: enhancement

Suggested reviewers: lucasfp13, ommeirelles, hellofanny

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding extension points to ValidateCartMutation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

codesandbox-ci · 2026-08-11T15:27:59Z

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/core/src/sdk/cart/index.ts`:
- Line 34: Update validateCart and the Cart type to preserve root-level fields
from StoreCartAdditional when constructing the SDK result, including custom
fields such as total, coupon, and totalizers. Apply the same preservation in
useReorder, while excluding these extension fields from input comparison and
update mapping. Add a regression test verifying one custom cart field survives
validation.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c3aee1ba-f933-4a4b-a184-0cdcb98ead9a

📥 Commits

Reviewing files that changed from the base of the PR and between 9e71296 and 0c1fcca.

⛔ Files ignored due to path filters (2)

packages/core/@generated/gql.ts is excluded by !**/@generated/**, !**/@generated/** and included by packages/**
packages/core/@generated/graphql.ts is excluded by !**/@generated/**, !**/@generated/** and included by packages/**

📒 Files selected for processing (5)

packages/api/src/platforms/vtex/resolvers/root.ts
packages/api/src/platforms/vtex/resolvers/validateCart.ts
packages/core/README.md
packages/core/src/customizations/src/fragments/ValidateCartMutation.ts
packages/core/src/sdk/cart/index.ts

sonar-workflows · 2026-08-11T15:51:19Z

Quality Gate passed

Issues

Measures

Project ID: vtex_faststore_f0a862d5-9557-49f9-8d09-de40caa76622

View in SonarQube

feat: add ValidateCartMutation extension points

0c1fcca

evander-corebiz requested a review from a team as a code owner August 11, 2026 15:26

evander-corebiz requested review from lucasfp13 and ommeirelles and removed request for a team August 11, 2026 15:26

coderabbitai Bot reviewed Aug 11, 2026

View reviewed changes

Comment thread packages/core/src/sdk/cart/index.ts

fix(core): preserve cart extension fields after validation

8d70424

coderabbitai Bot mentioned this pull request Aug 12, 2026

fix(api): preserve orderForm sales channel in validateCart #3435

Merged

4 tasks

Navigation Menu

Uh oh!

feat: add ValidateCartMutation extension points - #3441

feat: add ValidateCartMutation extension points#3441
evander-corebiz wants to merge 2 commits into
vtex:devfrom
evander-corebiz:feat/cart-mutation-extension

evander-corebiz commented Aug 11, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Aug 11, 2026 •

edited

Loading

Uh oh!

codesandbox-ci Bot commented Aug 11, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

sonar-workflows Bot commented Aug 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

evander-corebiz commented Aug 11, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What's the purpose of this pull request?

How it works?

How to test it?

Starters Deploy Preview

References

Summary by CodeRabbit

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

codesandbox-ci Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sonar-workflows Bot commented Aug 11, 2026

Quality Gate passed

Issues

Measures

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

evander-corebiz commented Aug 11, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Aug 11, 2026 •

edited

Loading

codesandbox-ci Bot commented Aug 11, 2026 •

edited

Loading