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	Client 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.

The defineExtensions function registers one or more React components by associating them with extension points. More information 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.

import { defineExtensions } from '@vtex/sales-app';
import { Recommendations } from './Recommendations';

export default defineExtensions({
  'cart.cart-list.after': Recommendations
});

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.

---

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

import { useCart } from '@vtex/sales-app'

const TotalItems = () => {
const cart = useCart()

  return <div>Items: {cart.items.length}</div>

}

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

import { useCart } from '@vtex/sales-app'

const TotalItems = () => {
const cart = useCart()

  const addItem = () => cart.addItem({
    quantity: 1,
    seller: '1',
    id: '8392'
  })

  return <button onClick={addItem}>Add to cart</button>

}

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	Order Form identifier for the current cart.
value	number	Total cart value.
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:

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

addGiftCard

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

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

Example using a redemption code:

import { useCart } from '@vtex/sales-app'

const AddGiftCard = () => {
const cart = useCart()

const add = async () => {
  await cart.addGiftCard('ABC-123', 'my-giftcard-provider')
  await cart.sync()
}

return <button onClick={add}>Add gift card</button>
}

---

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

import { useCartItem } from '@vtex/sales-app';

const CartItemDetails = () => {
  const { item } = useCartItem();

  return (
    <div>
      <p>Product: {item.id}</p>
      <p>Quantity: {item.quantity}</p>
      <img src={item.imageUrl} alt="Product image" />
    </div>
  );
};

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:

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

---

The useCurrentUser hook allows you to access current authenticated user's 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

import { useCurrentUser } from '@vtex/sales-app'

const CurrentUser = () => {
  const { name, email } = useCurrentUser()

  return <div>Current User: {name} - {email}</div>
}

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.

---

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

import { useExtension } from '@vtex/sales-app';

const ExtensionInfo = () => {
  const { account, extensionPoint } = useExtension();

  return (
    <div>
      <p>Account: {account}</p>
      <p>Extension Point: {extensionPoint}</p>
    </div>
  );
};

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 where your extension is hooked into.

---

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

import { usePDP } from '@vtex/sales-app'

const Product = () => {
  const { productSku } = usePDP()

  return <div>Product name: {productSku?.name}</div>
}

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.

---

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

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

Attachment

The Attachment type is defined as:

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

---

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

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

---

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

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

---

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:

type Totalizers = {
  id: string
  name: string
  value: number
};