Skip to content
decodecodeveloper docs
Storefront → Templates → Commerce

VTEX loaders and actions

Server-side data fetch and mutation API for VTEX.

@decocms/apps-vtex/loaders/* and @decocms/apps-vtex/actions/* are the server-side surface for VTEX. Loaders read; actions mutate. Both run inside the RequestContext with cookie propagation, instrumented fetch, and tracing.

Loaders

Imported individually or via the barrel @decocms/apps-vtex/loaders:

import { searchProducts, getCart, getUser } from "@decocms/apps-vtex/loaders";

address

FunctionPurpose
getAddressByPostalCode(zip)Resolve an address from a CEP/postal code
getUserAddresses(authCookie)Fetch the logged-in customer's address book

autocomplete

FunctionPurpose
autocompleteSearch({ query })IS autocomplete + product search; returns { searches, products }

brands

FunctionPurpose
listBrands()All brands in the catalog
getBrandById(id)Single brand

cart

FunctionPurpose
getCart(orderFormId?, opts?)Fetch the orderForm with DEFAULT_EXPECTED_SECTIONS

catalog

FunctionPurpose
searchProducts(props)Catalog product search
getProductByIdOrSku(idOrSku)Lookup by VTEX product ID or SKU ref
getProductVariations(productId)Variant list for a parent product
getProductSpecification(productId)Specifications array
getCrossSelling(productId, kind)Recommendations (similar, view-also, accessories)
getCategoryTree({ depth? })Full category tree
getBrands()All brands (alternate path)
getPageType(path)Page type detection (Department/Category/Brand/Product)
getFacets(query, map)Facet breakdown for a query

collections

FunctionPurpose
getCollections()List of catalog collections

legacy

Bridge functions for legacy Catalog/IS:

FunctionPurpose
legacyProductDetailsPageLegacy PDP shape
legacyProductListLegacy product list
legacyProductListingPageLegacy PLP shape
legacySuggestionsLegacy autocomplete

logistics

FunctionPurpose
listSalesChannels()All available sales channels
listPickupPoints()Pickup point catalog
listStockByStore(skuId)Per-store stock
FunctionPurpose
getNavbar()SiteNavigationElement[] from VTEX catalog

orders

FunctionPurpose
getOrderById(orderId)Single order
listOrders(authCookie, page)Paged customer orders
getOrderPlaced(orderId)Order summary (post-checkout receipt)

pageType

FunctionPurpose
resolvePageType(urlPath){ pageType, kind } for a URL — drives PDP/PLP routing

payment

FunctionPurpose
getPaymentSystems()Active payment methods
getUserPayments(authCookie)Saved cards / methods for the customer

profile

Profile reads via VTEX MasterData; details vary per implementation.

promotion

FunctionPurpose
getPromotionById(id)Promotion details
FunctionPurpose
getTopSearches()Trending search terms
validateProductSearch(term)Check if a term has results
getProductIdByTerm(term)First-match product ID

session

FunctionPurpose
getSession(items, authCookie)VTEX /api/sessions (REST)
getUserSessions()VTEX IO GraphQL session details

user

FunctionPurpose
getUser(authCookie)Person | null for the logged-in customer

wishlist & wishlistProducts

FunctionPurpose
getWishlist()Wishlist SKU list (GraphQL)
wishlistProducts(skus)Product details for wishlist items

workflow

FunctionPurpose
workflowProduct(id)Workflow-oriented single product
workflowProducts(props)Workflow product collection

Actions

Imported via the barrel:

import {
  getOrCreateCart,
  addItemsToCart,
  classicSignIn,
  notifyMe,
} from "@decocms/apps-vtex/actions";

analytics/sendEvent is a separate subpath: @decocms/apps-vtex/actions/analytics/sendEvent.

checkout (cart)

FunctionPurpose
getOrCreateCart()Create or fetch the user's cart (orderForm)
addItemsToCart({ items })Add SKUs
updateCartItems({ items })Update quantities, remove (qty 0)
addCoupons({ coupon })Apply a coupon
removeCoupons()Remove all coupons
simulate({ items, country, postalCode })Shipping/price simulation
getInstallments()Installment options
getShippingByPostalCode({ postalCode })Shipping calculation
addAttachment(...), addOffering(...), addProfileToOrderForm(...)Various orderForm mutations

All return an OrderForm. They use vtexFetchWithCookies to ensure cookies round-trip correctly.

auth

FunctionPurpose
startAuthentication()Begin auth flow
classicSignIn({ email, password })Email + password
accessKeySignIn({ email, accessKey })Email + magic link code
logout()Log out
refreshToken()Token refresh
recoverPassword({ email })Password recovery

session

FunctionPurpose
createSession()Bootstrap a session cookie
editSession({ items })Update session attributes (country, postal code)
deleteSession()Tear down

profile & address

CRUD for the customer profile and address book. *FromRequest variants pull cookie/auth from the inbound request automatically.

wishlist

FunctionPurpose
addItem({ productId, sku })Add to wishlist
removeItem({ id })Remove from wishlist

masterData

CRUD for VTEX MasterData documents (search, get, save, delete, attach files).

newsletter

FunctionPurpose
subscribe({ email }) / similarNewsletter opt-in flows

orders

FunctionPurpose
cancelOrder({ orderId, reason })Cancel an order

misc

Catch-all module: notifyMe (back-in-stock notifications), reviews, payment token deletes, and a few small utilities. See vtex/actions/misc.ts for the full list.

analytics/sendEvent

import sendEvent from "@decocms/apps-vtex/actions/analytics/sendEvent";

POSTs to VTEX analytics endpoints from the server side (so cookies and request context are correct). Use sparingly — most analytics is fine to send client-side.

Many actions (especially checkout, auth, session) use vtexFetchWithCookies from vtex/client.ts:

  • Forwards inbound request cookies to upstream VTEX.
  • Merges upstream Set-Cookie onto the response so the browser receives session/cart cookies.
  • Strips vtex_is_session / vtex_is_anonymous so middleware controls IS cookies (avoids cache key explosion).

If you write your own cart-related action, use vtexFetchWithCookies, not raw vtexFetch.

See also