Migration guide

Introduction

The Storefront API combines the strengths of server-side and client-side GraphQL: giving developers the tools they need to build modern, innovative storefronts, with the help of its clever queries to fetch exactly the data you need. No more, no less.

This means you’re cutting down on resource usage and boosting network speed, making everything run like a well-oiled machine. And with the ability to execute multiple queries or mutations in a single call, you’re looking at seriously enhanced performance. Plus, its strongly typed schema keeps everything reliable and consistent—no surprises here!

Performance isn’t just a feature; it’s at the core of the Storefront API, engineered to accommodate heavy frontend utilization without compromising on response times. This ensures a seamless user experience, even under significant load.

The API offers flexible configuration options, including session and no-session modes. This flexibility extends to the management of affiliates, allocation rules, brick-and-mortar locations, and customizable bundles, enriching the development experience. It’s a playground for developers who want to build something truly special.

Perks

• Seamless Selection Integration
  • Selections created in Centra backend can be easily checked out in the Storefront API by generating a selection link and using the claimSelection mutation (claimSelection(id: String!, hash: String!)). This makes it easier to manage selections and streamline the checkout process.
• Custom Attributes at Category and Selection Levels
  • The Storefront API supports custom attributes both at the category level and on individual selections. This flexibility allows you to tailor the experience for your customers and present highly personalized product options.
• Session and No-Session Modes The Storefront API offers two modes:
  • Session Mode: This allows users to manage carts, complete checkouts, and perform post-checkout operations based on the shopper’s session details (market, price list, language, etc.).
  • No-Session Mode: Stateless and designed to expose only the necessary data, this mode is ideal for building custom caches and efficiently handling data without retaining session information.
• Affiliate Tracking
  • The Storefront API enables you to track affiliate-driven sales easily. When a user arrives on your site via an affiliate link, the affiliate is connected to the selection. This helps you monitor and analyze orders generated through affiliate partnerships, such as influencer marketing efforts.
• Historical Orders
  • Once a customer completes the checkout process, the selection is automatically converted into an order. Registered users can log in and view their historical orders, improving the post-purchase experience and fostering customer retention.
• Advanced Filtering Options
  • The Storefront API provides comprehensive filtering capabilities (displayItems.filters) for narrowing down results by categories, collections, brands, and more. You can retrieve detailed filter data, such as category information, without requiring separate queries. This improves both performance and user experience.
• Powerful Search Capabilities
  • Storefront API enables you to implement a search bar with both strict and full-text search options. A simple search query allows the API to find matching results across various fields, improving product discoverability and enhancing the user experience.

Key Tips for Migrating from Checkout API to Storefront API

Optimize Your Data Fetching To ensure smooth performance and avoid overfetching, optimize the data you retrieve based on where the customer is in their journey. Fetch only the necessary data depending on whether the user is browsing, viewing the cart, or checking out.

Simply mapping Checkout API responses to the Storefront API will cause overfetching — meaning you end up pulling more data than necessary. To avoid this, plan ahead and make sure you're only fetching the data you actually need.

So how do you start the migration?

When starting, the Catalog is a good place to focus. For example, when fetching a list of display items, you likely don't need all the attributes — just key ones, like the color swatch.

On the PDP (Product Detail Page), you’ll need more detailed data, but only for one product. Related products are fetched similarly to a list view. The same goes for cart vs. checkout: in the cart, you don't need all the data that’s required at checkout.

For instance, in the cart, you probably don't need to load checkout fields like shipping costs. If you're calculating shipping totals, there’s no need to ask for details from services like Ingrid while still in the cart. The same applies to responses when adding products from the PDP.

Migration table

Customer

Update customer

Action	Checkout API	Shop API	Storefront API
Update customer address	PUT /address	PUT /customers/{email}	updateCustomer
Update customer	PUT /customer/update	PUT /customers/{email}	updateCustomer
Change password	PUT /password	PUT /customers/{email}	updateCustomer
Change email	PUT /email	PUT /customers/{email}	updateCustomer

Register, log in and log out

Action	Checkout API	Shop API	Storefront API
Register customer	POST /register	POST /customers/{email}	registerCustomer
Log in	POST /login/{email}	POST /customers/{email}/login	login
Log out	POST /logout	No matches	logout

Get customer data

Action	Checkout API	Shop API	Storefront API
Customer	GET /customer	GET /customers/{email} GET /customers/{email}/registered/{registered}	customer
Customer orders	POST /orders		customer

Subscription management

Action	Checkout API	Shop API	Storefront API
Customer subscriptions	POST /customer/subscriptions	POST /customers/{email}/subscriptions	customer subscriptionContracts
Add customer subscription	POST /customer/contracts/{contract}/subscription	POST /customers/{email}/contracts/{contract}/subscription	addSubscription
Update subscription quantity	PUT /customer/contracts/{contract}/subscription/{subscription}	PUT /customers/{email}/contracts/{contract}/subscription/{subscription}	updateSubscriptionQuantity
Change subscription address	PUT /subscription/address	PUT /subscription/address	changeSubscriptionContractAddress
Change subscription interval	PUT /subscription/interval	PUT /subscription/interval	updateSubscriptionInterval
Update subscription status	PUT /subscription/status	PUT /subscription/status	updateSubscriptionStatus

Reset password flow

Reset password has different flows. Need to be described separately

Action	Checkout API	Shop API	Storefront API
Send reset password email	POST /password-reset-email POST /password-reset-email/{email}	POST customers/{email}/password-reset-email	requestPasswordResetEmail
Verify hashes	No matches	POST /customer-password-reset-check	verifyResetPasswordHashes
Reset password	POST /password-reset	PUT /customers/{email}	resetPassword

Wishlist

Action	Checkout API	Shop API	Storefront API
Customer wishlist	GET /customer/wishlists/{wishlist}	No matches	customer
Add wishlist item	POST /customer/wishlists/{wishlist}/items/{displayItem}	No matches	addWishlistItem
Remove wishlist item	DELETE /customer/wishlists/{wishlist}/items/{displayItem}	No matches	removeWishlistItem

Product and newsletter subscriptions

Action	Checkout API	Shop API	Storefront API
Subscribe to back in stock	POST /back-in-stock-subscription	POST /customers/{email}/back-in-stock-subscription	subscribeToBackInStock
Subscribe to newsletter	POST /newsletter-subscription POST /newsletter-subscription/{email}	POST /customers/{email}/newsletter-subscription	subscribeToNewsletter

To expose Customer.gender in an API using Session mode scopes in the Storefront API plugin, select it as an option. Note that the gender format in Storefront API differs from Checkout API and requires mapping.

Checkout API	Storefront API
M	MALE
F	FEMALE
X	UNKNOWN

All attributes are exposed in the same format throughout the Storefront API. To align them with the Checkout API format, follow the attribute transformation rules.

Selection

Action	Checkout API	Shop API	Storefront API
Add item	POST /items/{item} POST /items/{item}/quantity/{quantity}	POST /selections/{selection}/items/{item} POST /selections/{selection}/items/{item}/quantity/{quantity}	addItem
Add flexible bundle	POST /items/bundles/{item}	POST /selections/{selection}/bundles	addFlexibleBundle
Add gift certificate	POST /items/gift-certificates/{giftCertificate} POST /items/gift-certificates/{giftCertificate}/amount/{amount}	POST /selections/{selection}/gift-certificates/{giftCertificate} POST/selections/{selection}/gift-certificates/{giftCertificate}/amount/{amount}	Not supported

Line modifications

Action	Checkout API	Shop API	Storefront API
Increase line quantity	POST /lines/{line} POST /lines/{line}/quantity/{quantity}	POST /selections/{selection}/lines/{line} POST /selections/{selection}/lines/{line}/quantity/{quantity}	updateLine
Reduce line quantity	DELETE /lines/{line}/quantity/{quantity}	DELETE /selections/{selection}/lines/{line}/quantity/{quantity}	updateLine
Reduce item quantity	Not supported	DELETE /selections/{selection}/items/{item}/quantity/{quantity}	updateLine
Delete line	DELETE /lines/{line}	DELETE /selections/{selection}/lines/{line}	deleteLine
Delete item	N\A	DELETE /selections/{selection}/items DELETE/selections/{selection}/items/{item}	N/A
Set line quantity	PUT /lines/{line}/quantity/{quantity}	PUT /selections/{selection}/lines/{line}/quantity/{quantity}	updateLine
Set item quantity	Not supported	PUT /selections/{selection}/items/{item}/quantity/{quantity}	updateLine
Remove line subscription plan	DELETE /lines/{line}/subscription-plan	DELETE /selections/{selection}/lines/{line}/subscription-plan	removeSubscriptionPlanFromLine
Update line subscription plan	PUT /lines/{line}/subscription-plan/{subscriptionPlan}	PUT /selections/{selection}/lines/{line}/subscription-plan/{subscriptionPlan}	updateLine

Selection modifications

Action	Checkout API	Shop API	Storefront API
Change country	PUT /countries/{country} PUT /countries/{country}/states/{state}	PUT /selections/{selection}/countries/{country}	setCountryState
Update market	PUT /selection	PUT /selections/{selection}/markets/{market}	setMarket
Update pricelist	PUT /selection	PUT /selections/{selection}/pricelists/{pricelist}	Automated by GeoIP, can be controlled via setCountryState
Change language	PUT /languages/{language}	PUT /selections/{selection}/languages/{language}	setLanguage
Set campaign site	PUT /campaign-site	Not supported	setCampaignSite
Set affiliate	Not supported	Not supported	setAffiliate
Remove customer	Not supported	DELETE /selections/{selection}/customers	Not supported
Attach customer	Not supported	PUT /selections/{selection}/customers/{customer}	Not supported
Set VAT exempt	Not supported	PUT /selections/{selection}/vat-exempt/{vatExempt}	Not supported
Apply gift card	POST /gift-card-apply	not supported	applyGiftCard

Remaining endpoints

Action	Checkout API	Shop API	Storefront API
Create selection	Created at first selection action	POST /selections	Created at first selection action
Get selection	GET /selection	GET /selections/{selection}	selection
Attach selection	PUT /selection/{selection}	No matches	setSelection
Claim selection	Not supported	POST /payment-links/{hash1}/{hash2}	claimSelection

Line prices

Checkout API	Shop API	Storefront API
priceEachAsNumber	priceEachAsNumber	line.unitOriginalPrice - applied campaigns appliedPromotions.value.value * quantity
priceEachWithoutTaxAsNumber	priceEachWithoutTaxAsNumber	(line.unitOriginalPrice - applied campaigns appliedPromotions.value.value * quantity) / tax percent
priceEachBeforeDiscountAsNumber	priceEachBeforeDiscountAsNumber	line.unitOriginalPrice
priceEachReductionAsNumber	priceEachReductionAsNumber	line.unitPriceReduction (includes campaign + voucher)
totalPriceBeforeDiscountAsNumber	totalPriceBeforeDiscountAsNumber	line.originalLineValue
totalPriceAsNumber	totalPriceAsNumber	line.lineValue + line vouchers appliedPromotions.value.value * line quantity
totalPriceAfterCampaignAsNumber	totalPriceAfterCampaignAsNumber	line.originalLineValue - applied campaigns * line quantity
totalPriceAfterDiscountAsNumber	totalPriceAfterDiscountAsNumber	line.lineValue
anyDiscount	anyDiscount	line.hasDiscount
taxPercent	taxPercent	line.taxPercent

Note: Unlike Checkout API and Shop API, which only include campaign promotions in line prices, the Storefront API includes all applied promotions. Therefore, to match the previous price format, you will need to calculate certain values independently.

Catalog

Queries

Action	Checkout API	Shop API	Storefront API
List products	GET products	GET products	displayItems
Search products	POST products	POST products/search	displayItems
Filter products	POST products	POST products/filter, GET products/{filter}/{value}	displayItems
Product Details	POST product/{product}	POST products	displayItem

Brands

Queries

Action	Checkout API	Shop API	Storefront API
List brands	GET brands	GET brands	brands

Collections

Queries

Action	Checkout API	Shop API	Storefront API
List collections	GET collections	GET collections	collections
Collection details		GET collections/{collection}	collections

Warehouses

Queries

Action	Checkout API	Shop API	Storefront API
List Warehouses	GET warehouses	GET warehouses	Not supported

Checkout migration

Checkout details

Action	Checkout API	Shop API	Storefront API
Set shipping method	PUT /shipping-methods/{shippingMethod}	PUT/selections/{selection}/shipping-method/{shippingMethod}	setShippingMethod
Set payment method	PUT /payment-methods/{paymentMethod}	PUT /selections/{selection}/payment-methods/{paymentMethod}	setPaymentMethod
Payment fields	PUT /payment-fields	POST /selections/{selection}/payment-fields PUT /selections/{selection}/checkout-fields	setAddress handleWidgetEvent

Vouchers

Action	Checkout API	Shop API	Storefront API
Add voucher	POST /vouchers	POST /selections/{selection}/vouchers/{voucher}	addVoucher
Add URI voucher	POST /vouchers	POST /selections/{selection}/voucher-uri/{voucher}	lookupUri
Remove voucher	DELETE /vouchers DELETE /vouchers/{voucher}	DELETE /selections/{selection}/vouchers DELETE /selections/{selection}/vouchers/{voucher}	removeVoucher
Remove URI voucher	DELETE /vouchers DELETE /vouchers/{voucher}	DELETE /selections/{selection}/voucher-uri/{voucher}	removeVoucher

Gift cards

Action	Checkout API	Shop API	Storefront API
Apply gift card	POST /gift-card-apply		applyGiftCard

Ship from Store

Action	Checkout API	Shop API	Storefront API
Set allocation rule	PUT /allocation-rule/{id}	PUT /selections/{selection}/allocation-rule/{allocationRule}	setAllocationRule
Set Brick and mortar	PUT /brick-and-mortar/{id}	PUT /selections/{selection}/brick-and-mortar/{brickAndMortar}	setBrickAndMortar
Fulfilment check	POST /fulfillment-check	POST /selections/{selection}/fulfillment-check	fulfillmentCheck

Payment process

Action	Checkout API	Shop API	Storefront API
Payment instructions	POST /payment	POST /selections/{selection}/payment	paymentInstructions
Payment result	POST /payment-result	POST /selections/{selection}/payment-result	paymentResult

Remaining

Action	Checkout API	Shop API	Storefront API
Address search	POST /address-search	POST /payment-methods/{paymentMethod}/address-search	Not supported
Receipt	GET /receipt	GET /selections/{selection}/receipt	order

Address search

Storefront API doesn’t support address search.

Totals

Storefront API provides selection totals under selection.checkout.totals. This list contains the selection summary per type.

Checkout API	Shop API	Storefront API
itemsTotalPriceAsNumber	itemsTotalPriceAsNumber	ITEMS_SUBTOTAL + discounts applied on lines.
totalDiscountPriceAsNumber	totalDiscountPriceAsNumber	DISCOUNT + CREDIT
shippingPriceAsNumber	shippingPriceAsNumber	SHIPPING
handlingCostAddedToShippingPrice	handlingCostPriceAsNumber	HANDLING
totalQuantity	totalQuantity	Sum of line.quantity
taxDeductedAsNumber	taxDeductedAsNumber	TAX_DEDUCT.taxPercent
taxAddedAsNumber	taxAddedAsNumber	TAX_ADDED.taxPercent
taxPercent	taxPercent	INCLUDING_TAX.taxPercent
grandTotalPriceAsNumber	grandTotalPriceAsNumber	GRAND_TOTAL
grandTotalPriceTaxAsNumber	grandTotalPriceTaxAsNumber	INCLUDING_TAX or TAX_ADDED