Adding Installment Information in the Product Details Page
This guide illustrates how you can display available installment options for products on your Product Details Page (PDP).
For detailed instructions on API extensions, refer to API extensions guide.
Context
You want to display installment details (number, value, payment system) on the PDP for products with installments. This functionality allows customers to see installment details directly on the product page, aiding their purchase decision.
Implementation
Create the GraphQL files
First, you need to set up the necessary GraphQL files to retrieve and structure the installment data.
- In your store repository, go to the
src
folder, if you don’t have one already, create a newgraphql
folder. - Inside
graphql
, create thevtex
folder. - In the
vtex
folder, create two other subfolders,resolvers
andtypeDefs
.
For further details on code implementation, see thevtex
folder available in the playground.store repository.
_10src _10┗ 📂 graphql _10 ┗ 📂vtex _10 ┣ 📂 resolvers _10 ┗ 📂 typeDefs
Define the types
Now that we have our file structure in place, let's define the data structure for our installment information using GraphQL.
In the
typeDefs
folder, create a product.graphql
file to define the schema. Add the following schema definitions.Installments
: Specifies the structure of each installment option. Each installment has properties for:installmentPaymentSystemName
: The name of the payment system used (e.g., Credit Card).installmentValue
: The value of each installment.installmentInterest
: The interest rate applied per installment.installmentNumber
: The total number of installments offered.StoreProduct
: This type is being extended to include a new field calledavailableInstallments
. This field is a list of installment objects, representing all the available installment options for the product.
Create the resolvers
Now that we've defined the structure of our installment data (GraphQL types), let's create the logic to retrieve and format this data using a resolver function. Resolvers essentially act as gateways between your frontend and backend, processing data requests.
In the
resolvers
folder, create a product.ts
file to handle the installment data logic. Add the following code.productResolver
: Defines a resolver for theStoreProduct
type.availableInstallments
: Function that retrieves the Installments data from thecommertialOffer
property of the first seller (sellers[0]
).installments.length
: Check if there are any installments (installments.length
). If not, an empty array is returned.- The code iterates through each installment and maps it to a new object with the desired properties (
installmentPaymentSystemName
,installmentValue
, etc.).
Consolidating the resolvers
In the
resolvers
folder, create an index.ts
file to consolidate the resolvers.- By default exporting resolvers, this file acts as a central hub for all your resolvers.
resolvers
:Combines the imported resolver with any other resolvers you might have in your project (represented by the ellipsis...
).
Using fragments
Now that we've defined the
availableInstallments
field using GraphQL types and resolvers, we need to specify where this data will be used in your storefront queries. This is achieved through GraphQL fragments.-
In the
src
folder of your store code, create afragments
folder. -
In the
fragments
folder, create the following files:ClientProduct.ts
: Defines the Client-Side fragment.ServerProduct.ts
: Defines the Server-Side fragment.
-
In the
ClientProduct.ts
file, define the GraphQL fragment for retrieving installment data.
gql
: Imported from @faststore/core/api to construct the GraphQL fragment.ClientProduct
: Fragment to indicate it extends the product query.- The fragment defines the specific fields we want to retrieve from the
availableInstallments
data structure.
Adding server-side product fragment for installment details
To ensure consistency in data retrieval across client-side and server-side, add a product fragment focusing on installment details. In the
ServerProduct.ts
file, add the following code.For further details on code implementation, see thefragments
folder available in the playground.store repository.
Formatting installment values
For a more user-friendly display, you can format the installment values to include currency symbols and proper locale formatting.
- In the
src
folder of your store code, create autils
folder. - Inside
utils
, create the filepriceFormatter.ts
and add the following.
FaststoreConfig
: Imported to access the current store's locale and currency settings.priceFormatter
: This function takes a numeric value and formats it according to the store's locale and currency.
For further details on code implementation, see theutils
folder available in the playground.store repository.
Create the new component with installments
Now that we've established the logic for retrieving installment data, let's create a new component to display this information alongside the buy button on the PDP.
-
In the
src/components
folder, create two new folders:BuyButtonWithDetails
: This folder keeps the component for our enhanced buy button with installment details.sections/CustomProductDetails
: This folder keeps the logic for overriding the default PDP buy button component.
-
Inside
BuyButtonWithDetails
folder, create two new files:BuyButtonWithDetails.tsx
buy-button-with-details.module.scss
-
Inside
BuyButtonWithDetails.tsx
add the following code.
priceFormatter
: Format installment values.styles
: Stylesheet for the BuyButtonWithDeatils imported from the.scss
file.usePDP
: Hook to retrieve the PDP context containing product and extension data.- We conditionally display the first installment option if it's interest-free (you can modify this to show all installments).
- The component renders a section containing the installment information and the buy button.
Creating the stylesheet for the component
Inside the
buy-button-with-details.module.scss
, add the following code. The stylesheet styles the component using SCSS. It defines styles for the installment information container and the buy button itself.Create a custom section
By including the
CustomProductDetails
section in the PDP, you replace the default buy button component with your enhanced BuyButtonWithDetails
component, which displays both the buy button and the installment information.In the folder
CustomProductDetails
, create the CustomProductDetails.tsx
and add the following code.For further details on code implementation, see theutils
folder available in the playground.store repository.
Create the GraphQL files
First, you need to set up the necessary GraphQL files to retrieve and structure the installment data.
- In your store repository, go to the
src
folder, if you don’t have one already, create a newgraphql
folder. - Inside
graphql
, create thevtex
folder. - In the
vtex
folder, create two other subfolders,resolvers
andtypeDefs
.
For further details on code implementation, see thevtex
folder available in the playground.store repository.
Define the types
Now that we have our file structure in place, let's define the data structure for our installment information using GraphQL.
In the
typeDefs
folder, create a product.graphql
file to define the schema. Add the following schema definitions.Installments
: Specifies the structure of each installment option. Each installment has properties for:installmentPaymentSystemName
: The name of the payment system used (e.g., Credit Card).installmentValue
: The value of each installment.installmentInterest
: The interest rate applied per installment.installmentNumber
: The total number of installments offered.StoreProduct
: This type is being extended to include a new field calledavailableInstallments
. This field is a list of installment objects, representing all the available installment options for the product.
Create the resolvers
Now that we've defined the structure of our installment data (GraphQL types), let's create the logic to retrieve and format this data using a resolver function. Resolvers essentially act as gateways between your frontend and backend, processing data requests.
In the
resolvers
folder, create a product.ts
file to handle the installment data logic. Add the following code.productResolver
: Defines a resolver for theStoreProduct
type.availableInstallments
: Function that retrieves the Installments data from thecommertialOffer
property of the first seller (sellers[0]
).installments.length
: Check if there are any installments (installments.length
). If not, an empty array is returned.- The code iterates through each installment and maps it to a new object with the desired properties (
installmentPaymentSystemName
,installmentValue
, etc.).
Consolidating the resolvers
In the
resolvers
folder, create an index.ts
file to consolidate the resolvers.- By default exporting resolvers, this file acts as a central hub for all your resolvers.
resolvers
:Combines the imported resolver with any other resolvers you might have in your project (represented by the ellipsis...
).
Using fragments
Now that we've defined the
availableInstallments
field using GraphQL types and resolvers, we need to specify where this data will be used in your storefront queries. This is achieved through GraphQL fragments.-
In the
src
folder of your store code, create afragments
folder. -
In the
fragments
folder, create the following files:ClientProduct.ts
: Defines the Client-Side fragment.ServerProduct.ts
: Defines the Server-Side fragment.
-
In the
ClientProduct.ts
file, define the GraphQL fragment for retrieving installment data.
gql
: Imported from @faststore/core/api to construct the GraphQL fragment.ClientProduct
: Fragment to indicate it extends the product query.- The fragment defines the specific fields we want to retrieve from the
availableInstallments
data structure.
Adding server-side product fragment for installment details
To ensure consistency in data retrieval across client-side and server-side, add a product fragment focusing on installment details. In the
ServerProduct.ts
file, add the following code.For further details on code implementation, see thefragments
folder available in the playground.store repository.
Formatting installment values
For a more user-friendly display, you can format the installment values to include currency symbols and proper locale formatting.
- In the
src
folder of your store code, create autils
folder. - Inside
utils
, create the filepriceFormatter.ts
and add the following.
FaststoreConfig
: Imported to access the current store's locale and currency settings.priceFormatter
: This function takes a numeric value and formats it according to the store's locale and currency.
For further details on code implementation, see theutils
folder available in the playground.store repository.
Create the new component with installments
Now that we've established the logic for retrieving installment data, let's create a new component to display this information alongside the buy button on the PDP.
-
In the
src/components
folder, create two new folders:BuyButtonWithDetails
: This folder keeps the component for our enhanced buy button with installment details.sections/CustomProductDetails
: This folder keeps the logic for overriding the default PDP buy button component.
-
Inside
BuyButtonWithDetails
folder, create two new files:BuyButtonWithDetails.tsx
buy-button-with-details.module.scss
-
Inside
BuyButtonWithDetails.tsx
add the following code.
priceFormatter
: Format installment values.styles
: Stylesheet for the BuyButtonWithDeatils imported from the.scss
file.usePDP
: Hook to retrieve the PDP context containing product and extension data.- We conditionally display the first installment option if it's interest-free (you can modify this to show all installments).
- The component renders a section containing the installment information and the buy button.
Creating the stylesheet for the component
Inside the
buy-button-with-details.module.scss
, add the following code. The stylesheet styles the component using SCSS. It defines styles for the installment information container and the buy button itself.Create a custom section
By including the
CustomProductDetails
section in the PDP, you replace the default buy button component with your enhanced BuyButtonWithDetails
component, which displays both the buy button and the installment information.In the folder
CustomProductDetails
, create the CustomProductDetails.tsx
and add the following code.For further details on code implementation, see theutils
folder available in the playground.store repository.
_10src _10┗ 📂 graphql _10 ┗ 📂vtex _10 ┣ 📂 resolvers _10 ┗ 📂 typeDefs
Results
Once you have set your development mode, you can see the changes locally by accessing a PDP, for example,
https://localhost:3000/adidas-mens-performance-polo-green-night-99984111/p
, and you will see the installment information for the product.Before
The PDP before adding the installment.
![{"base64":" ","img":{"width":948,"height":571,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":215607,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/before-installment___c06c92a26445e0dc97a33981f893358e.png"}}](https://vtexhelp.vtexassets.com/assets/docs/src/before-installment___c06c92a26445e0dc97a33981f893358e.png)
After
After applying the logic for the installments, the information is available above the
Buy Button
.![{"base64":" ","img":{"width":929,"height":676,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":240060,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/after-installment___77227bfcffcf9a25800effe9790100e1.png"}}](https://vtexhelp.vtexassets.com/assets/docs/src/after-installment___77227bfcffcf9a25800effe9790100e1.png)