Sales App extension hooks and types

VTEX Sales App

Explore the APIs and core types available for building Sales App extensions.

This guide introduces the Sales App APIs and core types used to build extensions.

The following APIs are available:

API	Category	Use case
`defineExtensions`	Function	Register components in extension points.
`useCart`	Hook	Read cart-level data or perform cart mutations, such as adding items, coupons, or gift cards.
`useCartItem`	Hook	Read data or perform mutations for a single cart item, such as changing quantity, attachments, or price.
`useCurrentUser`	Hook	Access authenticated user data.
`useExtension`	Hook	Access runtime context, such as the current account or the current extension point.
`usePDP`	Hook	Access product detail page data, specifically the current `productSku`.

Available types and their corresponding hooks include:

Types	Used by	Description
`CartItem`	`useCart`, `useCartItem`	An item in the cart, including product, quantity, seller, pricing, and attachments.
`ClientProfileData`	`useCart`	Customer data returned from the cart context.
`ProductSku`	`usePDP`	A product SKU, including identifying information, quantity, and pricing fields.
`Totalizers`	`useCart`	Summary totals from an orderForm or cart, such as shipping, taxes, or discounts.

API reference

`defineExtensions`

The defineExtensions function registers one or more React components by associating them with extension points. Learn more in Exploring Sales App extensions.

Use this function in your extension entry point file, such as src/index.tsx.

Usage

In the following example, Recommendations is rendered at the cart.cart-list.after extension point, which appears below the cart items list.

src/index.tsx


_10import { defineExtensions } from '@vtex/sales-app';
_10import { Recommendations } from './Recommendations';
_10
_10export default defineExtensions({
_10  'cart.cart-list.after': Recommendations
_10});

Parameters

The defineExtensions function accepts a single parameter, Record<ExtensionPoints, () => ReactNode>. The ExtensionPoints type represents the list of valid extension points available in VTEX Sales App.

`useCart`

The useCart hook allows you to access cart data and perform mutations that will reflect on other entities within the Sales App data layer.

This hook is available in the following extension points:

cart.cart-list.after
cart.cart-item.after
cart.order-summary.after
pdp.sidebar.before
pdp.sidebar.after
pdp.content.after

See all available extension points in the guide Exploring Sales App extensions.

Usage

src/index.tsx


_10import { useCart } from '@vtex/sales-app'
_10
_10const TotalItems = () => {
_10const cart = useCart()
_10
_10  return <div>Items: {cart.items.length}</div>
_10
_10}

You can also use useCart to interact with the Sales App data layer by mutating the cart item list:

src/index.tsx


_14import { useCart } from '@vtex/sales-app'
_14
_14const TotalItems = () => {
_14const cart = useCart()
_14
_14  const addItem = () => cart.addItem({
_14    quantity: 1,
_14    seller: '1',
_14    id: '8392'
_14  })
_14
_14  return <button onClick={addItem}>Add to cart</button>
_14
_14}

Parameters

The useCart hook doesn't accept any parameters.

Returns

The useCart hook returns an object with the following properties:

Property	Type	Description
`orderFormId`	`string \| undefined`	orderForm identifier for the current cart.
`value`	`number`	Cart total.
`items`	`CartItem[]`	Items currently in the cart.
`totalizers`	`Totalizers[]`	Aggregated cart totals.
`clientProfileData`	`ClientProfileData`	Customer profile data associated with the cart.
`giftCards`	`GiftCard[]`	Gift cards currently attached to the cart.
`addItem`	`(data: UseCartAddItemData) => Promise<void>`	Adds an item to the cart.
`removeItem`	`(id: string, index: number) => Promise<void>`	Removes an item from the cart.
`addCoupon`	`(coupon: string) => Promise<void>`	Applies a coupon to the cart.
`addGiftCard`	`(redemptionCodeOrGiftCard: string \| GiftCard, provider?: string) => Promise<void>`	Adds a gift card to the cart payment data. You can provide either a redemption code (as a `string`) with an optional `provider`, or a GiftCard object if you already have the gift card details.
`sync`	`() => Promise<void>`	Syncs the cart with the latest Order Form data.

`addItem`

In the addItem property, the UseCartAddItemData type is an object with the following structure:


_10type UseCartAddItemData = {
_10  id: string;
_10  quantity: number;
_10  seller: string;
_10  attachments?: Attachment[];
_10};

`addGiftCard`

In the addGiftCard property, the GiftCard type is an object with the following structure:


_12export type GiftCard = {
_12  id: string
_12  redemptionCode?: string | null
_12  name: string
_12  caption: string
_12  value: number
_12  balance: number
_12  provider: string
_12  groupName?: string | null
_12  inUse: boolean
_12  isSpecialCard: boolean
_12}

Example using a redemption code:

src/index.tsx


_12import { useCart } from '@vtex/sales-app'
_12
_12const AddGiftCard = () => {
_12const cart = useCart()
_12
_12const add = async () => {
_12  await cart.addGiftCard('ABC-123', 'my-giftcard-provider')
_12  await cart.sync()
_12}
_12
_12return <button onClick={add}>Add gift card</button>
_12}

`useCartItem`

The useCartItem hook provides access to detailed information about an individual cart item. This is useful when you need to retrieve or display specific data related to a single item in the cart.

This hook is available in the following extension point:

cart.cart-item.after

See all available extension points in the guide Exploring Sales App extensions.

Usage

src/index.tsx


_13import { useCartItem } from '@vtex/sales-app';
_13
_13const CartItemDetails = () => {
_13  const { item } = useCartItem();
_13
_13  return (
_13    <div>
_13      <p>Product: {item.id}</p>
_13      <p>Quantity: {item.quantity}</p>
_13      <img src={item.imageUrl} alt="Product image" />
_13    </div>
_13  );
_13};

Parameters

The useCartItem hook doesn't accept any parameters.

Returns

The useCartItem hook returns an object with the following properties:

Property	Type	Description
`item`	`CartItem[] \| undefined`	Cart item data for the current item.
`itemIndex`	`number \| undefined`	Index of the current item in the cart.
`changeItem`	`(data: UseCartItemChangeItemData) => Promise<void>`	Updates the item data.
`changePrice`	`(price: number) => Promise<void>`	Changes the item price when manual price is enabled. To check whether the manual price is active, use Get orderForm configuration. To enable it, use Update orderForm configuration and set `allowManualPrice` to `true`.

`changeItem`

In the changeItem property, the UseCartItemChangeItemData type is an object with the following structure:


_10type UseCartItemChangeItemData = {
_10  quantity?: number
_10  attachments?: Attachment[]
_10}

`useCurrentUser`

The useCurrentUser hook allows you to access currently authenticated user data, like name and email.

This hook is available in the following extension point:

menu.drawer-content

See all available extension points in the guide Exploring Sales App extensions.

Usage

src/index.tsx


_10import { useCurrentUser } from '@vtex/sales-app'
_10
_10const CurrentUser = () => {
_10  const { name, email } = useCurrentUser()
_10
_10  return <div>Current User: {name} - {email}</div>
_10}

Parameters

The useCurrentUser hook doesn't accept any parameters.

Returns

The useCurrentUser hook returns an object with the following properties:

Property	Type	Description
`name`	`string`	Name of the current user.
`email`	`string`	Email address of the current user.

`useExtension`

The useExtension hook allows you to access information about the current account and the extension point in which your extension is running.

This hook is available for all extension points. See the full list in the guide Exploring Sales App extensions.

Usage

src/index.tsx


_12import { useExtension } from '@vtex/sales-app';
_12
_12const ExtensionInfo = () => {
_12  const { account, extensionPoint } = useExtension();
_12
_12  return (
_12    <div>
_12      <p>Account: {account}</p>
_12      <p>Extension Point: {extensionPoint}</p>
_12    </div>
_12  );
_12};

Parameters

The useExtension hook doesn't accept any parameters.

Returns

The useExtension hook returns an object with the following structure:

Property	Type	Description
`account`	`string`	The current account name where the extension is running.
`extensionPoint`	`ExtensionPointsType`	The name of the extension point your extension is hooked to.

`usePDP`

The usePDP hook allows you to access Product Detail Page (PDP) data and perform mutations that will reflect on other entities within the Sales App data layer.

This hook is available in the following extension points:

pdp.sidebar.before
pdp.sidebar.after
pdp.content.after

See all available extension points in the guide Exploring Sales App extensions.

Usage

src/index.tsx


_10import { usePDP } from '@vtex/sales-app'
_10
_10const Product = () => {
_10  const { productSku } = usePDP()
_10
_10  return <div>Product name: {productSku?.name}</div>
_10}

Parameters

The usePDP hook doesn't accept any parameters.

Returns

The usePDP hook returns an object with the following property:

Property	Type	Description
`productSku`	`ProductSku`	Product SKU data for the current product detail page.

Types

`CartItem`

The CartItem type represents an item in the cart. Its signature and the types used follow this contract:


_13 type CartItem = {
_13  id: string
_13  name: string
_13  quantity: number
_13  seller: string
_13  sellingPrice: number
_13  listPrice: number
_13  manualPrice?: number
_13  price: number
_13  imageUrl: string
_13  productRefId?: string
_13  attachments?: Attachment[]
_13};

Attachment

The Attachment type is defined as:


_10type Attachment = {
_10   name: string;
_10   content: Record<string, string>;
_10};

`ClientProfileData`

The ClientProfileData type represents the structure of the data returned for a client. Its signature and the types used follow this contract:


_10type ClientProfileData = {
_10  email: string | null;
_10  document: string | null;
_10  phone: string | null;
_10};

`ProductSku`

The ProductSku type represents the structure of a product SKU, including quantity and pricing details. Its signature and the types used follow this contract:


_10type ProductSku = {
_10  id: string;
_10  name: string;
_10  quantity: number;
_10  price: number;
_10  listPrice: number;
_10  sellingPrice?: number;
_10};

`Totalizers`

The Totalizers type represents the structure of the summary totals returned in an orderForm or cart, such as shipping, taxes, or discounts. Its signature and the types used follow this contract:


_10type Totalizers = {
_10  id: string
_10  name: string
_10  value: number
_10};