Services

Purpose

Services is the theme’s client-side service layer that centralizes API calls and shared storefront workflows.

It exposes servicesreusabledefault as the common SDK used by components/reusables for cart, checkout, profile, offer, and payment operations.

Where it's rendered

No direct Liquid render call was found for Reusables/Services/Default in this workspace.

Inputs (Liquid render parameters)

This reusable is rendered without Liquid parameters.

Template behavior (Liquid + Alpine)

This reusable does not render UI.

Its role is to register the global JavaScript object servicesreusabledefault, which is then consumed by other components and reusables.

Data contract (JS runtime)

Document runtime state shape, factories, and main state fields.

JavaScript

Standard function conventions

1) Pattern: Axios + normalized return

Most methods follow this structure:

Call an endpoint using axios.get/post/put/delete.

Normalize the response via:

getAxiosResponse(response, context)

Return the normalized object:

On exceptions:

Log with a method-specific console.error('<method> failed:', e)

Return e.response (raw Axios error response), or return the cancel error when using cancel tokens.

2) Context strings

getAxiosResponse is always called with a stable context string (usually the method name), e.g.:

this.getAxiosResponse(response, 'addToCart')

This makes error logs searchable and consistent.

3) Cancellation

Some methods cancel the previous request before starting a new one, using:

axios.CancelToken.source()

The service caches Axios CancelToken sources on internal properties of the services object.

4) Side effects

Several methods intentionally do more than “just call an API”. Common side effects include:

Updating localStorage (cartToken, checkoutToken, cartData)

Calling setCookie(...)

Updating Alpine stores:

Alpine.store('cart').update(...)

Alpine.store('checkout').set(...)

Alpine.store('checkout').validateStep(...)

Alpine.store('checkout').isUpdating = true/false

Alpine.store('modal').shouldReinitialize = true

5) fetch vs axios

Some search endpoints use fetch(...) and return raw JSON (not the normalized wrapper). These are exceptions and are documented explicitly below.

API reference (grouped by category)

General

getCartData

clearCart

teardownKlarnaPayments

uuidv4

completeCheckout

fetchUsers

deleteCompanyLogo

getCartData()

Fetches the current cart payload for the active session.

Notes:

Used by cart/checkout-related flows to refresh cartData after mutations.

Returns a normalized response (via getAxiosResponse).

teardownKlarnaPayments()

Performs cleanup for Klarna Payments UI state.

Notes:

Intended to be called when leaving a Klarna step / when re-initializing checkout payment forms.

This method may interact with payment-specific globals/scripts loaded in the layout.

getAxiosResponse(response, context = "")

Normalizes an Axios response into a stable shape.

Parameters:

response: Axios response object (or falsy).

context: optional string used in logs.

Behavior:

If response.status is not 2xx, logs a structured error and returns:

{ success: false, status, error: response }

If 2xx, returns:

{ success: true, status, data: response.data }

uuidv4()

Generates a random GUID-like string using crypto.getRandomValues.

Used for:

checkoutToken generation

file upload session ids

setShopranosCookie(value, expiresAt)

POST /api/cookies.

Parameters:

value: cookie value.

expiresAt: expiration date/time.

Returns:

normalized response via getAxiosResponse.

internalUploadFile(file, url, endpoint = null)

Uploads a file in chunks (200000 bytes per chunk) using fetch and FormData.

Parameters:

file: a File object.

url: base upload URL.

endpoint: optional extra query param ?endpoint=....

Returns:

guid (string) for the upload session, or null on failure.

Notes:

Uses uuidv4() internally.

Does not use axios.

generateTextFromAI(data, cultureCode, currency)

POSTs product-offer prompt payload to /api/ai/product/offer/notes and returns normalized response.

fetchProductMixProducts(params)

GET /api/product-mix/my-list?{params} and returns normalized response.

Shopping Lists

getShoppingLists

getShoppingLists()

GET /api/ShoppingList.

Side effects:

Alpine.store('modal').shouldReinitialize = true.

Returns normalized response.

createShoppingList(data)

POST /api/ShoppingList.

Parameters:

data: request payload (shopping list creation model).

Returns normalized response.

deleteShoppingList(alias)

DELETE /api/ShoppingList/{alias}.

Parameters:

alias: shopping list alias.

Returns normalized response.

updateShoppingList(list)

PUT /api/ShoppingList/{list.alias}.

Parameters:

list: full list object; must include alias.

Returns normalized response.

importShoppingList(alias, file)

Imports items into an existing list.

Steps:

Uploads the file via internalUploadFile(file, '/api/file') → returns guid

POST /api/ShoppingList/import-items/{alias}/{guid}

Parameters:

alias: list alias.

file: import file.

Returns normalized response.

exportShoppingList(alias)

Exports items to a file.

POST /api/ShoppingList/export-items/{alias} with { responseType: 'blob' }.

Creates a browser download named ShoppingList-{alias}.xlsx.

Parameters:

alias: list alias.

Returns normalized response.

Wishlist

clearWishlist

Endpoint: GET /api/products/liquid with query string params.

Parameters:

searchCriteria: object of query params. Only non-null/undefined values are included.

Returns:

object | null

Returns parsed JSON on success.

Returns null and logs on non-OK response.

findProductsByCriteriaExtended(searchCriteria)

Like findProductsByCriteria but uses:

GET /api/products/search-extended

Parameters:

searchCriteria: object of query params.

Returns:

parsed JSON.

Errors:

Throws an Error when the response is not OK.

setReadAnnouncementIds(ids)

PUT /api/customer/addresses/{addressId}.

Parameters:

data: address payload.

addressId: address id.

Returns normalized response.

deleteUserAddress(addressId)

DELETE /api/customer/addresses/{addressId}.

Parameters:

addressId: address id.

Returns normalized response.

setUserAddressAsPrimary(addressId)

POST /api/customer/addresses/setdefault/{addressId}.

Parameters:

addressId: address id.

Returns normalized response.

accountLogin(data)

POST /api/account/login.

Parameters:

data: login payload.

Side effects on success (status == 200):

GET /api/cart/user to retrieve a user cart.

Sets localStorage.cartToken, cookie cartToken, and localStorage.cartData.

Returns normalized response.

accountLoginWithCustomerId(customerId)

Step 2 of the multi-customer login flow. Called after accountLogin when a user has multiple customer memberships and must select which customer to log in as.

POST /api/account/login/{customerId}.

Parameters:

customerId: the selected customer id.

Side effects on success (status == 200):

GET /api/cart/user to retrieve the user cart for the selected customer.

Sets localStorage.cartToken, cookie cartToken, and localStorage.cartData.

Returns normalized response.

accountRegister(data)

POST /api/account/register.

Parameters:

data: register payload.

Returns normalized response.

registerUser(data, token)

POST /api/account/confirmInvitation/{token}.

file: logo file.

customerId: customer id.

Returns normalized response.

deleteCompanyLogo()

DELETE /api/customer/logo.

Returns normalized response.

Cart

addToCart(productId, variantId, quantity, finalPrice, originalPrice, showPopUp = true)

Adds a single item to the cart.

Endpoint:

POST /api/cart/{cartToken}/add

Parameters:

productId: product id.

variantId: product variant id.

quantity: quantity to add.

finalPrice: used for GA payload (price).

originalPrice: used for GA payload (initialPrice).

showPopUp: passed to $store.cart.update(...) to control UI feedback.

Preconditions / side effects:

Cancels previous cart update via cancelTokenSource.

Ensures localStorage.checkoutToken exists (creates one via uuidv4() and sets cookie checkoutToken).

Updates localStorage.cartToken + cookie cartToken.

If $store.cart exists, calls:

Alpine.store('cart').update(cartData, [{ ...addedItem, addedQuantity: quantity }], showPopUp)

If cart has items, sends GA event addToCart.

Returns normalized response.

addMultipleToCart(variations, showPopUp = true)

Adds multiple items to cart in one request.

Endpoint:

POST /api/cart/{cartToken}/addmultiple

Parameters:

variations: array of objects with at least:

productId

productVariantId

quantity

dim1Value, dim2Value

price, initialPrice

showPopUp: passed to cart store update.

Side effects:

Updates token/cookie.

Updates $store.cart once with successfully added products.

Sends GA addToCart event.

Returns normalized response.

updateProductCart(cartData, cancelToken)

Updates the cart.

Endpoint:

PUT /api/cart/{cartToken}

Parameters:

cartData: cart update payload.

cancelToken: Axios cancel token.

Side effects:

Updates token/cookie.

Calls Alpine.store('cart').update(cartData).

Returns normalized response (or cancel error).

updateProductQuantity(data, cancelToken)

Validates/resolves requested quantity.

Endpoint:

POST /api/cart/{cartToken}/resolveQuantity

Parameters:

data: object with:

productId

productVariantId

requestedQuantity

cancelToken: Axios cancel token.

Returns normalized response (or cancel error).

clearCart()

Clears all cart items.

Endpoint:

DELETE /api/cart/{cartToken}/all

Side effects:

Sends GA removeFromCart based on stored localStorage.cartData.

Updates token/cookie.

Calls Alpine.store('cart').update(cartData).

Returns normalized response.

removeFromCart(variantId)

Removes an item by variant id.

Endpoint:

DELETE /api/cart/{cartToken}/{variantId}

Parameters:

variantId: product variant id.

Side effects:

Sends GA removeFromCart for the removed line.

Updates token/cookie.

Calls Alpine.store('cart').update(cartData).

Returns normalized response.

getCartValidation()

Fetches calculated cart validation and returns a simplified error summary.

Endpoint:

GET /api/cart/calculated/{cartToken}/

Cancellation:

Cancels the previous calculation request using calculatecartCancelTokenSource.

Returns:

On success: { isSuccess, lines: [{ type, count, lineIds[] }] }

On failure: returns e.response.

importCart(type, file)

Imports cart lines from a CSV/Excel file using chunked upload.

Endpoint:

POST /api/cart/import?format={type}

Parameters:

type: import format (for example Csv or Excel).

file: File, FileList, or array-like file input; the first valid File is used.

Behavior:

Splits the file into 200000-byte chunks and posts each chunk with FormData.

Uses Axios option validateStatus: () => true so 202 chunk-accepted and final 200 responses are handled explicitly by the method.

Returns early for non-200/202 responses.

validateStatus

importCart(...) sets Axios validateStatus: () => true so chunk responses are not rejected by Axios and can be handled explicitly in code (202 continue, 200 final payload, other statuses return early).

Side effects on success:

When payload contains cart.token, updates localStorage.cartToken and cookie cartToken.

Returns:

Final import payload on success, or e.response on failure.

exportCart(type)

POST /api/cart/export with the selected format and triggers file download from the returned URL.

Quantity Constraints (Progressive Hydration)

Product cards (grid, list, classic) request personalized quantity constraints client-side so the server can render from a cached, personalization-free view model. All calls that happen in the same browser tick are batched into a single request.

hydrateProductConstraints(product)

Enqueues product for constraints hydration and returns a Promise that resolves once the shared batch completes.

Requires product.id and a non-empty product.productVariants[].

Schedules a setTimeout(..., 0) flush on first call per tick so all cards on the same page share one request.

On resolution, writes variant.quantityConstraints for each variant in the product.

On failure, falls back to _applyDefaultConstraints(product).

POST /api/cart/quantity-constraints/by-products — body is an array of product ids.

_applyDefaultConstraints(product)

Writes permissive fallback constraints (min: 1, max: 999999, step: 1, isValid: true) to every variant of product.

Called automatically by hydrateProductConstraints on network failure, or directly by callers that need an immediate safe default.

Checkout

updateCheckout(data, checkoutStep = null)

Updates checkout.

Endpoint:

POST /api/checkout/update/{checkoutToken}

Parameters:

data: checkout update payload.

checkoutStep: optional string; when present, triggers step validation.

Side effects:

Injects data.cartItems = Alpine.store('cart').items.

Toggles Alpine.store('checkout').isUpdating.

On success:

Alpine.store('checkout').set(returnResponse.data)

Alpine.store('checkout').validateStep(checkoutStep, true)

On error:

Alpine.store('checkout').globalError = true

validateStep(checkoutStep, false)

Returns normalized response.

proceedToCheckout(data)

High-level checkout continuation.

Behavior:

Calls updateCheckout(data).

If there is a payment provider, calls initiatePayment(checkoutData).

Otherwise calls completeCheckout().

Returns normalized response.

initiatePayment(data)

Initiates payment and performs provider-specific redirects.

Endpoint:

POST /api/payment/initiate/{checkoutToken}

Parameters:

data: checkout data; must contain data.payment.provider.

Behavior:

Redirects the browser when redirectUrl is returned for providers like PayPal/JCC/Stripe/Nexi.

Builds and auto-submits provider forms for EDPS/Epay/CardLink.

Injects and executes HTML snippet for Klarna.

Otherwise falls back to completeCheckout().

On errors:

Redirects to /checkout/error.

loadKlarnaPaymentsScript

Loads or reuses the Klarna Payments script and resolves when the script is ready.

buildKlarnaPaymentsContainer

Builds/returns the DOM container used to host Klarna embedded payment content.

showKlarnaPaymentsError

Displays/logs a Klarna-specific error state for failed setup/authorization steps.

cancelKlarnaPayments

Cancels/tears down any in-flight Klarna UI/payment state.

handleKlarnaPayments

Coordinates Klarna payment flow selection and delegates to inline/HPP handlers.

handleKlarnaPaymentsInLine

Initializes and runs the embedded (inline) Klarna flow.

handleKlarnaPaymentsHpp

Initializes and runs the hosted payment page (HPP) Klarna flow.

postKlarnaPaymentsAuthorize

Submits Klarna authorization payload and returns the backend authorization result.

completeCheckout()

Completes checkout.

POST /api/checkout/complete/{checkoutToken}.

updateOfferPricing

Updates offer pricing (line-level or aggregate) and returns normalized response.

createOffer

Creates a new offer and returns normalized response.

updateOffer

Updates an existing offer and returns normalized response.

rejectOffer

Rejects/cancels an existing offer and returns normalized response.

createQuote

Creates a quote payload/workflow entry and returns normalized response.

Global Alpine stores

This reusable may update these stores when they exist (depending on the called method):

$store.cart

$store.checkout

$store.modal

$store.toast (indirectly; most callers handle toasts themselves)

Services / API calls

This reusable is the services layer itself.

It calls backend endpoints under /api/... via axios (mostly) and fetch (in specific search endpoints).

Dependencies

JS: Reusables/Services/Default.js

Translations: Reusables/Services/Default.json

Notes

servicesreusabledefault includes both:

“thin” API wrappers (call endpoint + normalize)

“orchestrators” that update stores/local storage and trigger GA events.

Services

Purpose#

Where it's rendered#

Inputs (Liquid render parameters)#

Template behavior (Liquid + Alpine)#

Data contract (JS runtime)#

JavaScript#

Standard function conventions#

1) Pattern: Axios + normalized return#

2) Context strings#

3) Cancellation#

4) Side effects#

5) fetch vs axios#

API reference (grouped by category)#

General#

getCartData#

clearCart#

teardownKlarnaPayments#

uuidv4#

completeCheckout#

fetchUsers#

deleteCompanyLogo#

getCartData()#

teardownKlarnaPayments()#

getAxiosResponse(response, context = "")#

uuidv4()#

setShopranosCookie(value, expiresAt)#

internalUploadFile(file, url, endpoint = null)#

generateTextFromAI(data, cultureCode, currency)#

fetchProductMixProducts(params)#

Shopping Lists#

getShoppingLists#

getShoppingLists()#

createShoppingList(data)#

deleteShoppingList(alias)#

updateShoppingList(list)#

importShoppingList(alias, file)#

exportShoppingList(alias)#

Wishlist#

clearWishlist#

clearWishlist()#

addItemToWishlist(productId)#

removeItemFromWishlist(productId)#

Navbar (Search + announcements)#

findProductsByCriteria(searchCriteria)#

findProductsByCriteriaExtended(searchCriteria)#

setReadAnnouncementIds(ids)#

Form#

sendEmail(data)#

internalUploadFiles(fields)#

uploadContactFormFile(file)#

Profile (Account, addresses, managed users)#

accountForgotPassword(data)#

changePassword(data)#

changePasswordProfile(data)#

updateUserProfile(data)#

createUserAddress(data)#

updateUserAddress(data, addressId)#

deleteUserAddress(addressId)#

setUserAddressAsPrimary(addressId)#

accountLogin(data)#

accountLoginWithCustomerId(customerId)#

accountRegister(data)#

registerUser(data, token)#

deleteUser(user)#

updateUser(user)#

inviteUser(data)#

fetchUsers()#

uploadCompanyLogo(file, customerId)#

deleteCompanyLogo()#

Cart#

addToCart(productId, variantId, quantity, finalPrice, originalPrice, showPopUp = true)#

addMultipleToCart(variations, showPopUp = true)#

updateProductCart(cartData, cancelToken)#

updateProductQuantity(data, cancelToken)#

clearCart()#

removeFromCart(variantId)#

getCartValidation()#

importCart(type, file)#

validateStatus#

Purpose

Where it's rendered

Inputs (Liquid render parameters)

Template behavior (Liquid + Alpine)

Data contract (JS runtime)

JavaScript

Standard function conventions

1) Pattern: Axios + normalized return

2) Context strings

3) Cancellation

4) Side effects

5) fetch vs axios

API reference (grouped by category)

General

getCartData

clearCart

teardownKlarnaPayments

uuidv4

completeCheckout

fetchUsers

deleteCompanyLogo

getCartData()

teardownKlarnaPayments()

getAxiosResponse(response, context = "")

uuidv4()

setShopranosCookie(value, expiresAt)

internalUploadFile(file, url, endpoint = null)

generateTextFromAI(data, cultureCode, currency)

fetchProductMixProducts(params)

Shopping Lists

getShoppingLists

getShoppingLists()

createShoppingList(data)

deleteShoppingList(alias)

updateShoppingList(list)

importShoppingList(alias, file)

exportShoppingList(alias)

Wishlist

clearWishlist

clearWishlist()

addItemToWishlist(productId)

removeItemFromWishlist(productId)

Navbar (Search + announcements)

findProductsByCriteria(searchCriteria)

findProductsByCriteriaExtended(searchCriteria)

setReadAnnouncementIds(ids)

Form

sendEmail(data)

internalUploadFiles(fields)

uploadContactFormFile(file)

Profile (Account, addresses, managed users)

accountForgotPassword(data)

changePassword(data)

changePasswordProfile(data)

updateUserProfile(data)

createUserAddress(data)

updateUserAddress(data, addressId)

deleteUserAddress(addressId)

setUserAddressAsPrimary(addressId)

accountLogin(data)

accountLoginWithCustomerId(customerId)

accountRegister(data)

registerUser(data, token)

deleteUser(user)

updateUser(user)

inviteUser(data)

fetchUsers()

uploadCompanyLogo(file, customerId)

deleteCompanyLogo()

Cart

addToCart(productId, variantId, quantity, finalPrice, originalPrice, showPopUp = true)

addMultipleToCart(variations, showPopUp = true)

updateProductCart(cartData, cancelToken)

updateProductQuantity(data, cancelToken)

clearCart()

removeFromCart(variantId)

getCartValidation()

importCart(type, file)

validateStatus

exportCart(type)