Commerce
An online store: catalogue, search, cart, checkout, orders, returns, reviews and more. Portal.commerce.create(storeRef) returns a client for one store, grouped into facets (catalog, search, cart, checkout, account, consent, reviews, b2b, subscriptions, marketplace).
Quick start
const shop = window.Portal.commerce.create('STORE_REF');
await shop.init();
const page = await shop.catalog.productsPage({ limit: 12 });
console.log(page.products.length, 'products');
await shop.cart.add({ variant_ref: 'VARIANT_REF' });
shop.on('cart:updated', (cart) => console.log('Cart changed', cart));API reference
shop
A commerce client bound to one store (Portal.commerce.create(storeRef)), grouped into facets: catalog, search, cart, checkout, account, consent, reviews, b2b, subscriptions, marketplace. The flat methods below the facets are older aliases kept for existing pages.
account
Orders, returns and balances.
Type: PortalCommerceAccountFacet (read-only)
const account = shop.account;attachPricing()
Alias of catalog.attachPricing().
const result = shop.attachPricing(products, dpItems);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
products | T[] | Yes | The products. |
dpItems | ReadonlyArray<PortalDirectPaymentItem | Record<string, unknown>> | Yes | One item in a SINGLE_PAY Direct Payment's catalogue — something that can be put on an invoice. |
Returns
Returns Array<PortalCommercePricedProduct<T>>.
b2b
Business buying.
Type: PortalCommerceB2bFacet (read-only)
const b2b = shop.b2b;beginCheckout()
Alias of checkout.begin().
const checkoutBeginResult = await shop.beginCheckout(email);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
email | string | No | An e-mail address. |
Returns
Resolves with a PortalCommerceCheckoutBeginResult: The answer to shop.checkout.begin().
cart
The cart (also callable to read it).
Type: PortalCommerceCartFacet (read-only)
const cart = shop.cart;catalog
Catalogue reads.
Type: PortalCommerceCatalogFacet (read-only)
const catalog = shop.catalog;checkout
Checkout.
Type: PortalCommerceCheckoutFacet (read-only)
const checkout = shop.checkout;completeCheckout()
Alias of checkout.complete().
const checkoutConfirmResult = await shop.completeCheckout(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The data to send. |
payload.invoice_ref | string | Yes | — |
payload.direct_payment_ref | string | Yes | — |
payload.processor_ref | string | Yes | — |
payload.cart_ref | string | Yes | — |
payload.lines | object[] | Yes | The lines involved. |
payload.lines[].item_ref | string | Yes | The Direct Payments item reference. |
payload.lines[].name | string | Yes | The name. |
payload.lines[].quantity | number | Yes | How many. |
payload.recipe_hash | string | No | — |
Returns
Resolves with a PortalCommerceCheckoutConfirmResult: The answer to shop.checkout.complete().
consent
Privacy consent.
Type: PortalCommerceConsentFacet (read-only)
const consent = shop.consent;eachProductPage()
Pages through the catalogue: for await (const page of shop.eachProductPage(query, maxPages)).
const result = shop.eachProductPage(query, maxPages);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
query | PortalCommerceProductQuery | Yes | Filters and paging for catalogue reads (shop.catalog.products(), productsPage(), Portal.commerce.getProducts()). |
maxPages | number | Yes | — |
Returns
Returns AsyncGenerator<PortalCommerceListPage<Record<string, unknown>>, void, undefined>.
init()
Loads the store's public settings (and the shopper's consent). Call once before anything else. Resolves with the settings.
const result = await shop.init();Returns
Resolves with the server's record as a plain object.
listSubscriptions()
Alias of subscriptions.list().
const result = await shop.listSubscriptions();Returns
Resolves with Array<Record<string, unknown>>.
marketplace
Multi-vendor features.
Type: PortalCommerceMarketplaceFacet (read-only)
const marketplace = shop.marketplace;off()
Stops listening.
shop.off(event, listener);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
event | PortalCommerceEventName | Yes | The events shop.on() / shop.off() understand. |
listener | (payload: unknown) => void | Yes | Function called when it happens. |
on()
Listens for a store event; the payload depends on the event (cart:updated carries the cart).
shop.on(event, listener);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
event | PortalCommerceEventName | Yes | The events shop.on() / shop.off() understand. |
listener | (payload: unknown) => void | Yes | Function called when it happens. |
products()
Alias of catalog.products().
const result = await shop.products(query);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
query | PortalCommerceProductQuery | No | Filters and paging for catalogue reads (shop.catalog.products(), productsPage(), Portal.commerce.getProducts()). |
Returns
Resolves with unknown.
rentalAvailability()
06: per-day units free for a rental variant. Add with custom_attributes { rental_starts_on, rental_ends_on }.
const rentalAvailability = await shop.rentalAvailability(variantRef, from, to);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
variantRef | string | Yes | The variant's reference. |
from | string | Yes | The start of the range. |
to | string | Yes | The end of the range. |
Returns
Resolves with a PortalCommerceRentalAvailability: The answer to rentalAvailability(): the rules and the per-day free units of a rental variant.
reviews
Reviews and questions.
Type: PortalCommerceReviewsFacet (read-only)
const reviews = shop.reviews;search
Search and recommendations.
Type: PortalCommerceSearchFacet (read-only)
const search = shop.search;subjectKey()
The shopper's anonymous consent key (stored in the browser).
const value = shop.subjectKey();Returns
Returns a string.
subscriptions
Product subscriptions.
Type: PortalCommerceSubscriptionsFacet (read-only)
const subscriptions = shop.subscriptions;shop.account
shop.account — the signed-in shopper's orders, returns and balances.
balances()
Gift-card and store-credit balances of an owner.
const result = await shop.account.balances(ownerRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
ownerRef | string | Yes | — |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
accounts | Array<Record<string, unknown>> | Yes | — |
cancelOrder()
Cancels an order that has not shipped.
const result = await shop.account.cancelOrder(referenceNum, reason);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
reason | string | No | — |
Returns
Resolves with the server's record as a plain object.
cancelReturn()
Withdraws a return request.
await shop.account.cancelReturn(referenceNum);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
Returns
Resolves when the call has completed.
order()
One order.
const result = await shop.account.order(referenceNum);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
Returns
Resolves with the server's record as a plain object.
orderLookup()
Look an order up without signing in: its number and the email it was placed with.
const result = await shop.account.orderLookup(number, email);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
number | string | Yes | The order number shown to the shopper. |
email | string | Yes | An e-mail address. |
Returns
Resolves with the server's record as a plain object.
orders()
The shopper's orders; scope: 'open' limits to unfinished ones.
const result = await shop.account.orders(opts);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
opts | object | No | Optional settings. |
opts.scope | 'open' | 'all' | No | Which records to include. |
opts.limit | number | No | The most items to return. |
opts.cursor | string | No | The cursor returned by the previous call, to get the next page. |
Returns
Resolves with Array<Record<string, unknown>>.
orderUpsell()
Adds a post-purchase upsell to an existing order.
const result = await shop.account.orderUpsell(orderReferenceNum, variantRef, quantity);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
orderReferenceNum | string | Yes | The order's reference number. |
variantRef | string | Yes | The variant's reference. |
quantity | number | No | How many. |
Returns
Resolves with the server's record as a plain object.
purchase()
What an invoice paid for, as the store sees it (status, amounts, refunds, lines).
const purchaseView = await shop.account.purchase(invoiceRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
invoiceRef | string | Yes | The invoice's reference. |
Returns
Resolves with a PortalCommercePurchaseView: What an invoice paid for, as the store sees it (shop.account.purchase()).
requestExchange()
Asks to exchange items of an order.
const result = await shop.account.requestExchange(orderReferenceNum, payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
orderReferenceNum | string | Yes | The order's reference number. |
payload | Record<string, unknown> | Yes | The data to send. |
Returns
Resolves with the server's record as a plain object.
requestReturn()
Asks to return items from an order.
const result = await shop.account.requestReturn(orderReferenceNum, payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
orderReferenceNum | string | Yes | The order's reference number. |
payload | object | Yes | The data to send. |
payload.reason | string | Yes | — |
payload.note | string | No | — |
payload.lines | object[] | Yes | The lines involved. |
payload.lines[].order_line_id | number | Yes | — |
payload.lines[].quantity | number | Yes | How many. |
Returns
Resolves with the server's record as a plain object.
returnEligibility()
Which lines of an order can still be returned and until when.
const result = await shop.account.returnEligibility(orderReferenceNum);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
orderReferenceNum | string | Yes | The order's reference number. |
Returns
Resolves with the server's record as a plain object.
returnLabel()
The prepaid return label of an approved return.
const result = await shop.account.returnLabel(returnReferenceNum);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
returnReferenceNum | string | Yes | — |
Returns
Resolves with the server's record as a plain object.
returns()
The shopper's return requests.
const result = await shop.account.returns();Returns
Resolves with Array<Record<string, unknown>>.
subscribeAlert()
Back-in-stock alert: e-mails the address when the variant is available again.
await shop.account.subscribeAlert(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The data to send. |
payload.variant_reference_num | string | Yes | — |
payload.email | string | Yes | An e-mail address. |
Returns
Resolves when the call has completed.
track()
Shipment tracking for an order, by number and email.
const result = await shop.account.track(number, email);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
number | string | Yes | The order number shown to the shopper. |
email | string | Yes | An e-mail address. |
Returns
Resolves with the server's record as a plain object.
shop.b2b
shop.b2b — business buying: quick order by SKU, quotes, payment terms and approvals.
payOnTerms()
Pay on invoice terms (net netDays) for a company account.
const result = await shop.b2b.payOnTerms(companyId, netDays);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
companyId | number | Yes | The company account's id. |
netDays | number | Yes | Pay on invoice terms (net netDays) for a company account. |
Returns
Resolves with the server's record as a plain object.
quickOrder()
Adds many SKUs to the cart at once.
const result = await shop.b2b.quickOrder(rows);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
rows | object[] | Yes | A list of objects, described below. |
rows[].sku | string | Yes | Your stock-keeping code. |
rows[].quantity | number | Yes | How many. |
Returns
Resolves with the server's record as a plain object.
requestApproval()
Sends a cart to an approver group for approval before it can be bought.
const result = await shop.b2b.requestApproval(cartRef, approverGroup);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
cartRef | string | Yes | The cart's reference. |
approverGroup | string | No | — |
Returns
Resolves with the server's record as a plain object.
requestQuote()
Asks for a quote for some lines.
const result = await shop.b2b.requestQuote(lines, email);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
lines | Array<Record<string, unknown>> | Yes | The lines involved. |
email | string | No | An e-mail address. |
Returns
Resolves with the server's record as a plain object.
respondQuote()
Accepts, declines or counters a quote.
const result = await shop.b2b.respondQuote(referenceNum, action, lines);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
action | 'accept' | 'decline' | 'counter' | Yes | The action. |
lines | Array<Record<string, unknown>> | No | The lines involved. |
Returns
Resolves with the server's record as a plain object.
shop.cart
shop.cart — the shopper's cart. Callable: await shop.cart() reads it; the members change it. Every change resolves with the updated cart.
shop.cart()
Reads the cart; null when the shopper has none yet.
const result = await shop.cart();Returns
Resolves with PortalCommerceCart \| null.
add()
Adds a variant to the cart (creating the cart if needed).
const cart = await shop.cart.add(input);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
input | PortalCommerceAddToCartInput | Yes | What shop.cart.add() sends. |
Returns
Resolves with a PortalCommerceCart: The shopper's cart as the server computes it.
addFavorite()
Marks a product as a favourite; resolves with the updated list.
const commerceFavorites = await shop.cart.addFavorite(productRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
productRef | string | Yes | The product's reference. |
Returns
Resolves with an array of PortalCommerceFavorite.
applyCredit()
Uses the shopper's store credit (in cents) on the cart.
const result = await shop.cart.applyCredit(cents);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
cents | number | Yes | — |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
value_state | Record<string, unknown> | Yes | The gift-card or credit balance state. |
applyDiscount()
Applies a discount code. Rejects when the code is not valid.
const cart = await shop.cart.applyDiscount(code);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
code | string | Yes | The code to apply. |
Returns
Resolves with a PortalCommerceCart: The shopper's cart as the server computes it.
applyGiftCard()
Applies a gift card code to the cart.
const result = await shop.cart.applyGiftCard(code);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
code | string | Yes | The code to apply. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
value_state | Record<string, unknown> | Yes | The gift-card or credit balance state. |
cart()
Same as calling the facet: await shop.cart().
const result = await shop.cart.cart();Returns
Resolves with PortalCommerceCart \| null.
favorites()
The shopper's favourite products.
const commerceFavorites = await shop.cart.favorites();Returns
Resolves with an array of PortalCommerceFavorite.
moveSavedToCart()
Moves a saved item back into the cart.
const cart = await shop.cart.moveSavedToCart(savedId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
savedId | number | Yes | The saved item's id. |
Returns
Resolves with a PortalCommerceCart: The shopper's cart as the server computes it.
quickOrder()
Bulk add by SKU (B2B quick order).
const result = await shop.cart.quickOrder(rows);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
rows | object[] | Yes | A list of objects, described below. |
rows[].sku | string | Yes | Your stock-keeping code. |
rows[].quantity | number | Yes | How many. |
Returns
Resolves with the server's record as a plain object.
recover()
Restores an abandoned cart from the token in a recovery e-mail link.
const result = await shop.cart.recover(token);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
token | string | Yes | A token issued by the server (see the description above). |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
cart | PortalCommerceCart | Yes | — |
removeDiscount()
Removes the applied discount code.
const cart = await shop.cart.removeDiscount();Returns
Resolves with a PortalCommerceCart: The shopper's cart as the server computes it.
removeFavorite()
Removes a product from the favourites; resolves with the updated list.
const commerceFavorites = await shop.cart.removeFavorite(productRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
productRef | string | Yes | The product's reference. |
Returns
Resolves with an array of PortalCommerceFavorite.
removeLine()
Removes a line.
const cart = await shop.cart.removeLine(lineId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
lineId | number | Yes | The cart line's id. |
Returns
Resolves with a PortalCommerceCart: The shopper's cart as the server computes it.
removeSaved()
Deletes a saved item.
const cart = await shop.cart.removeSaved(savedId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
savedId | number | Yes | The saved item's id. |
Returns
Resolves with a PortalCommerceCart: The shopper's cart as the server computes it.
saveLineForLater()
Moves a line out of the cart into "saved for later".
const cart = await shop.cart.saveLineForLater(lineId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
lineId | number | Yes | The cart line's id. |
Returns
Resolves with a PortalCommerceCart: The shopper's cart as the server computes it.
setBusinessTaxId()
Sets a business tax / VAT id; valid says whether it was verified (null = could not be checked).
const result = await shop.cart.setBusinessTaxId(businessTaxId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
businessTaxId | string | Yes | — |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
business_tax_id | string | null | Yes | — |
valid | boolean | null | Yes | True when the value was accepted. |
setShippingAddress()
The address the cart is shipped to (and taxed for): { name, line1, line2?, city, state, postal_code, country, phone? }. Needed before checkout.begin() on a store that ships or charges tax by address.
const cart = await shop.cart.setShippingAddress(address);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
address | Record<string, unknown> | Yes | — |
Returns
Resolves with a PortalCommerceCart: The shopper's cart as the server computes it.
setShippingMethod()
Choose one of shippingMethods() by its id; null clears the choice.
const cart = await shop.cart.setShippingMethod(shippingMethodId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
shippingMethodId | number | null | Yes | The id of one of shippingMethods(). |
Returns
Resolves with a PortalCommerceCart: The shopper's cart as the server computes it.
shippingMethods()
The shipping methods open to the cart's address, each with its id, label and price. Call setShippingAddress() first.
const result = await shop.cart.shippingMethods();Returns
Resolves with Array<Record<string, unknown>>.
updateLine()
Sets a line's quantity (0 removes it).
const cart = await shop.cart.updateLine(lineId, quantity);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
lineId | number | Yes | The cart line's id. |
quantity | number | Yes | How many. |
Returns
Resolves with a PortalCommerceCart: The shopper's cart as the server computes it.
shop.catalog
shop.catalog — read products, categories, collections and markets.
attachPricing()
Joins the Direct Payments item prices onto products, in the browser: a product has no price of its own, only direct_payment_item_reference_num. dpItems are the items of the store's Direct Payment (dp.getItems(); the store settings name it in direct_payment). A product whose item is not found comes back with price_cents 0 and purchasable false.
const result = shop.catalog.attachPricing(products, dpItems);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
products | T[] | Yes | The products. |
dpItems | ReadonlyArray<PortalDirectPaymentItem | Record<string, unknown>> | Yes | dpItems are the items of the store's Direct Payment (dp.getItems(); the store settings name it in direct_payment). |
Returns
Returns Array<PortalCommercePricedProduct<T>>.
Examples
const shop = window.Portal.commerce.create('STORE_REF');
await shop.init();
const dp = window.Portal.directPayments.create('DP_REF');
await dp.initializeDirectPayment();
const page = await shop.catalog.productsPage({ limit: 12 });
const priced = shop.catalog.attachPricing(page.products, dp.getItems());
priced.forEach((product) => console.log(product.name, product.price_cents / 100));categories()
The product categories.
const result = await shop.catalog.categories();Returns
Resolves with unknown.
collections()
The curated collections.
const result = await shop.catalog.collections();Returns
Resolves with Array<Record<string, unknown>>.
markets()
The selling markets (country / currency groups) and the one currently selected.
const result = await shop.catalog.markets();Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
markets | Array<Record<string, unknown>> | Yes | — |
current | string | No | — |
product()
One product by slug or reference, with its variants.
const result = await shop.catalog.product(slugOrRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
slugOrRef | string | Yes | The product's slug or reference. |
Returns
Resolves with unknown.
productImages()
The images of a product (slug or reference): { images: [address,...] }.
const result = await shop.catalog.productImages(slugOrRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
slugOrRef | string | Yes | The product's slug or reference. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
images | string[] | Yes | — |
products()
One page of products (see productsPage() for the typed, cursor-based variant).
const result = await shop.catalog.products(query);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
query | PortalCommerceProductQuery | No | Filters and paging for catalogue reads (shop.catalog.products(), productsPage(), Portal.commerce.getProducts()). |
Returns
Resolves with unknown.
productsPage()
One page of products with the cursor for the next: { products, pageSize, nextCursor, hasMore }.
const result = await shop.catalog.productsPage(query);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
query | PortalCommerceProductQuery | No | Filters and paging for catalogue reads (shop.catalog.products(), productsPage(), Portal.commerce.getProducts()). |
Returns
Resolves with PortalCommerceListPage<Record<string, unknown>>.
rentalAvailability()
06: per-day units free for a rental variant (YYYY-MM-DD, at most 92 days).
const rentalAvailability = await shop.catalog.rentalAvailability(variantRef, from, to);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
variantRef | string | Yes | The variant's reference. |
from | string | Yes | The start of the range. |
to | string | Yes | The end of the range. |
Returns
Resolves with a PortalCommerceRentalAvailability: The answer to rentalAvailability(): the rules and the per-day free units of a rental variant.
setMarket()
Switches the shopper to a market; prices and currency follow.
const result = await shop.catalog.setMarket(marketRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
marketRef | string | Yes | — |
Returns
Resolves with the server's record as a plain object.
variantFor()
The variant matching a set of option choices, e.g. { Size: 'M', Color: 'Blue' }; null when no variant matches.
const result = await shop.catalog.variantFor(productRef, options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
productRef | string | Yes | The product's reference. |
options | Record<string, string> | Yes | Optional settings. |
Returns
Resolves with Record<string, unknown> \| null.
shop.checkout
shop.checkout — turning the cart into a paid order. Flow: begin() → build and pay an invoice with Direct Payments → attach() → complete().
abort()
Abandon the checkout in progress and release what it held.
await shop.checkout.abort();Returns
Resolves when the call has completed.
addresses()
The signed-in shopper's saved addresses.
const result = await shop.checkout.addresses();Returns
Resolves with Array<Record<string, unknown>>.
addressSuggest()
Address completion while the shopper types.
const result = await shop.checkout.addressSuggest(query);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Filters and options. |
Returns
Resolves with Array<Record<string, unknown>>.
attach()
Links the invoice the shopper is paying to the cart, BEFORE charging it, so the server can recover the order if the page dies during payment. Pass checkout_recipe.hash from begin() as recipeHash so the server can refuse an invoice built from a stale recipe (EC_E_RECIPE_STALE); it also rejects with EC_E_RECIPE_EXPIRED once the recipe has expired, in which case begin checkout again.
await shop.checkout.attach(cartRef, invoiceRef, recipeHash);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
cartRef | string | Yes | The cart's reference. |
invoiceRef | string | Yes | The invoice's reference. |
recipeHash | string | No | Pass checkout_recipe.hash from begin() as recipeHash so the server can refuse an invoice built from a stale recipe (EC_E_RECIPE_STALE); it also rejects with EC_E_RECIPE_EXPIRED once the recipe has expired, in which case begin checkout again. |
Returns
Resolves when the call has completed.
begin()
Starts checkout: re-prices the cart and returns what the invoice must contain.
const checkoutBeginResult = await shop.checkout.begin(email);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
email | string | No | An e-mail address. |
Returns
Resolves with a PortalCommerceCheckoutBeginResult: The answer to shop.checkout.begin().
buyAgain()
Puts the lines of a past order back into the cart.
const cart = await shop.checkout.buyAgain(orderReferenceNum);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
orderReferenceNum | string | Yes | The order's reference number. |
Returns
Resolves with a PortalCommerceCart: The shopper's cart as the server computes it.
complete()
Finishes checkout after payment: turns the cart into an order.
const checkoutConfirmResult = await shop.checkout.complete(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The data to send. |
payload.invoice_ref | string | Yes | The paid invoice. |
payload.direct_payment_ref | string | Yes | The Direct Payment it was paid on. |
payload.processor_ref | string | Yes | The processor that took the payment. |
payload.cart_ref | string | Yes | The cart being converted. |
payload.lines | object[] | Yes | The invoice lines. |
payload.lines[].item_ref | string | Yes | The Direct Payments item reference. |
payload.lines[].name | string | Yes | The name. |
payload.lines[].quantity | number | Yes | How many. |
payload.recipe_hash | string | No | checkout_recipe.hash from begin(). |
Returns
Resolves with a PortalCommerceCheckoutConfirmResult: The answer to shop.checkout.complete().
convertGuest()
Turns a guest order into an account order after the guest signs up.
await shop.checkout.convertGuest(orderReferenceNum);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
orderReferenceNum | string | Yes | The order's reference number. |
Returns
Resolves when the call has completed.
express()
Express checkout (wallet buttons): contact details and a shipping address in one call.
const result = await shop.checkout.express(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The data to send. |
payload.contact | Record<string, unknown> | No | — |
payload.shipping_address | Record<string, unknown> | No | — |
Returns
Resolves with the server's record as a plain object.
extras()
Gift options, a customer note, terms acceptance and similar extras on the cart.
const cart = await shop.checkout.extras(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | Record<string, unknown> | Yes | The data to send. |
Returns
Resolves with a PortalCommerceCart: The shopper's cart as the server computes it.
methods()
The payment methods open for a country and an amount (in cents).
const result = await shop.checkout.methods(country, amountCents);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
country | string | Yes | An ISO country code. |
amountCents | number | Yes | An amount in cents. |
Returns
Resolves with Array<Record<string, unknown>>.
paymentFailed()
Tells the store the payment for a cart failed (starts recovery e-mails).
const result = await shop.checkout.paymentFailed(cartRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
cartRef | string | Yes | The cart's reference. |
Returns
Resolves with the server's record as a plain object.
payOnTerms()
B2B: pay on invoice terms (net netDays) for a company account.
const result = await shop.checkout.payOnTerms(companyId, netDays);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
companyId | number | Yes | The company account's id. |
netDays | number | Yes | B2B: pay on invoice terms (net netDays) for a company account. |
Returns
Resolves with the server's record as a plain object.
saveAddress()
Saves an address to the signed-in shopper's address book.
const result = await shop.checkout.saveAddress(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The data to send. |
payload.label | string | No | — |
payload.address | Record<string, unknown> | Yes | — |
payload.is_default | boolean | No | — |
Returns
Resolves with the server's record as a plain object.
state()
The state of the checkout in progress.
const result = await shop.checkout.state();Returns
Resolves with the server's record as a plain object.
upsell()
Adds an upsell variant during checkout.
const result = await shop.checkout.upsell(variantRef, quantity);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
variantRef | string | Yes | The variant's reference. |
quantity | number | No | How many. |
Returns
Resolves with the server's record as a plain object.
shop.consent
shop.consent — the shopper's privacy choices; analytics and marketing features respect them.
allows()
Whether the shopper allows this purpose (terms are always true once accepted).
const ok = shop.consent.allows(purpose);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
purpose | string | Yes | What the sign-in is for. One of analytics, marketing_email, advertising, personalisation, terms. |
Returns
Returns a boolean.
load()
Reads the shopper's stored consent from the server (init() already does).
await shop.consent.load();Returns
Resolves when the call has completed.
set()
Records the shopper's choice for analytics or marketing e-mail.
await shop.consent.set(purpose, granted);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
purpose | 'analytics' | 'marketing_email' | Yes | What the sign-in is for. |
granted | boolean | Yes | — |
Returns
Resolves when the call has completed.
subjectKey()
The anonymous key this shopper's consent is stored under.
const value = shop.consent.subjectKey();Returns
Returns a string.
shop.marketplace
shop.marketplace — a multi-vendor store: browse vendors and apply to sell.
apply()
Apply to sell on the marketplace.
await shop.marketplace.apply(body);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
body | object | Yes | The text of the message. |
body.name | string | Yes | The name. |
body.email | string | Yes | An e-mail address. |
body.bio | string | No | — |
Returns
Resolves when the call has completed.
vendor()
One vendor by slug.
const result = await shop.marketplace.vendor(slug);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | Yes | The URL slug. |
Returns
Resolves with the server's record as a plain object.
vendorProducts()
The products of one vendor.
const result = await shop.marketplace.vendorProducts(slug);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | Yes | The URL slug. |
Returns
Resolves with Array<Record<string, unknown>>.
vendors()
The vendors of the marketplace.
const result = await shop.marketplace.vendors();Returns
Resolves with Array<Record<string, unknown>>.
shop.reviews
shop.reviews — product reviews and questions.
ask()
Asks a question about a product.
const result = await shop.reviews.ask(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The data to send. |
payload.product_reference_num | string | Yes | — |
payload.body | string | Yes | The text of the message. |
payload.asker_name | string | No | — |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The record's reference number. |
status | string | Yes | The status word. |
eligibility()
Whether this person may review this order line.
const result = await shop.reviews.eligibility(productRef, orderLineId, siteUserRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
productRef | string | Yes | The product's reference. |
orderLineId | number | Yes | — |
siteUserRef | string | Yes | The site user's reference. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
eligible | boolean | Yes | — |
list()
The approved reviews of a product.
const result = await shop.reviews.list(productRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
productRef | string | Yes | The product's reference. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
reviews | Array<Record<string, unknown>> | Yes | The reviews. |
questions()
The questions asked about a product.
const result = await shop.reviews.questions(productRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
productRef | string | Yes | The product's reference. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
questions | Array<Record<string, unknown>> | Yes | — |
submit()
Submits a review (rating 1-5); it may wait for moderation (status).
const result = await shop.reviews.submit(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The data to send. |
payload.order_line_id | number | Yes | — |
payload.site_user_reference | string | Yes | — |
payload.rating | number | Yes | A rating from 1 to 5. |
payload.body | string | Yes | The text of the message. |
payload.author_name | string | No | — |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The record's reference number. |
status | string | Yes | The status word. |
vote()
Votes a review helpful or not.
await shop.reviews.vote(referenceNum, helpful);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
helpful | boolean | Yes | — |
Returns
Resolves when the call has completed.
shop.search
shop.search — ranked product search, suggestions and recommendations.
facets()
Facet counts for a query, without needing the hits.
const searchResult = await shop.search.facets(query);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Filters and options. |
Returns
Resolves with a PortalCommerceSearchResult: The answer to a search.
recentlyViewed()
The products this shopper looked at recently.
const result = await shop.search.recentlyViewed();Returns
Resolves with Array<Record<string, unknown>>.
recommendations()
Recommended products of a kind (for example 'related'), optionally for one product.
const result = await shop.search.recommendations(kind, productRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
kind | string | Yes | — |
productRef | string | No | The product's reference. |
Returns
Resolves with Array<Record<string, unknown>>.
search()
Searches the catalogue.
const searchResult = await shop.search.search(query, options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Filters and options. |
options | PortalCommerceSearchOptions | No | Options of shop.search.search(). |
Returns
Resolves with a PortalCommerceSearchResult: The answer to a search.
suggest()
Completions for a search box as the shopper types.
const suggestResult = await shop.search.suggest(prefix);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
prefix | string | Yes | — |
Returns
Resolves with a PortalCommerceSuggestResult: The answer to shop.search.suggest().
shop.subscriptions
shop.subscriptions — recurring product subscriptions (boxes, refills).
cancel()
Not available yet: rejects. Cancel with Direct Payments (dp.subscription.cancel()).
await shop.subscriptions.cancel(subscriptionRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
subscriptionRef | string | Yes | The subscription's reference. |
Returns
Resolves when the call has completed.
list()
The shopper's subscriptions.
const result = await shop.subscriptions.list();Returns
Resolves with Array<Record<string, unknown>>.
pause()
Not available yet: rejects. Manage the payer's subscription with Direct Payments (dp.subscription).
await shop.subscriptions.pause(subscriptionRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
subscriptionRef | string | Yes | The subscription's reference. |
Returns
Resolves when the call has completed.
setBox()
Chooses the items of a subscription box.
await shop.subscriptions.setBox(subscriptionRef, boxSelection);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
subscriptionRef | string | Yes | The subscription's reference. |
boxSelection | string[] | Yes | — |
Returns
Resolves when the call has completed.
setFrequency()
Not available yet: rejects.
await shop.subscriptions.setFrequency(subscriptionRef, tierRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
subscriptionRef | string | Yes | The subscription's reference. |
tierRef | string | Yes | The tier's reference. |
Returns
Resolves when the call has completed.
skip()
Skips the next delivery.
await shop.subscriptions.skip(subscriptionRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
subscriptionRef | string | Yes | The subscription's reference. |
Returns
Resolves when the call has completed.
swap()
Swaps the product of a subscription.
await shop.subscriptions.swap(subscriptionRef, payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
subscriptionRef | string | Yes | The subscription's reference. |
payload | Record<string, unknown> | Yes | The data to send. |
Returns
Resolves when the call has completed.
window.Portal.commerce
Portal.commerce — the entry point of the shop SDK: create a client for a store.
create()
Creates a client for one store (by its reference).
const instance = window.Portal.commerce.create(storeRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
storeRef | string | Yes | The store's reference. |
Returns
Returns a PortalCommerceInstance: A commerce client bound to one store (Portal.commerce.create(storeRef)), grouped into facets: catalog, search, cart, checkout, account, consent, reviews, b2b, subscriptions, marketplace.
getCategories()
Reads categories, optionally of one store.
const result = await window.Portal.commerce.getCategories(store);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
store | string | No | The store's reference. |
Returns
Resolves with unknown.
getProducts()
Reads products without a store instance (pass query.store).
const result = await window.Portal.commerce.getProducts(query);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
query | PortalCommerceProductQuery | No | Filters and paging for catalogue reads (shop.catalog.products(), productsPage(), Portal.commerce.getProducts()). |
Returns
Resolves with unknown.
Types
PortalCommerceAddToCartInput
What shop.cart.add() sends.
| Name | Type | Required | Description |
|---|---|---|---|
variant_ref | string | Yes | The variant (the exact buyable version of a product) to add. |
quantity | number | No | How many; default 1. |
custom_attributes | Record<string, unknown> | No | Buyer choices stored on the line (engraving text, and for rentals rental_starts_on / rental_ends_on). |
PortalCommerceCart
The shopper's cart as the server computes it. Totals are authoritative: never add them up yourself.
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The cart's reference. |
store_reference_num | string | Yes | The store it belongs to. |
currency | string | Yes | ISO currency code. |
status | string | Yes | open, checkout, converted... |
email | string | null | No | The shopper's e-mail once known. |
shipping_method_id | number | null | No | The chosen shipping method id, or null. |
requires_shipping | boolean | No | True when the cart contains something that must be shipped. |
discount_code | string | null | No | The discount code applied. |
promotion_code | string | null | No | The promotion code applied. |
promotion_messages | string[] | No | Messages about promotions ("add $5 for free shipping"). |
free_shipping | boolean | No | True when a promotion makes shipping free. |
lines | PortalCommerceCartLine[] | Yes | The lines. |
line_count | number | Yes | Number of lines. |
subtotal_cents | number | Yes | Sum of the lines in cents. |
discount_cents | number | Yes | Discounts in cents (positive number taken off). |
shipping_cents | number | Yes | Shipping in cents. |
tax_cents | number | Yes | Tax in cents. |
deposit_cents | number | No | 06: rental deposits (their own Direct Payments item), included in total_cents. |
total_cents | number | Yes | What the shopper pays, in cents. |
show_quantity | boolean | No | Store setting: show quantity controls. |
allow_save_for_later | boolean | No | Store setting: offer "save for later". |
allow_favorites | boolean | No | Store setting: offer favourites. |
saved_for_later | PortalCommerceSavedItem[] | No | Lines saved for later. |
cart_hold_minutes | number | No | How long stock is held for the cart, in minutes. |
inventory | object[] | No | Live stock of the cart's products. |
inventory[].product_ref | string | No | — |
inventory[].variant_ref | string | No | — |
inventory[].available_quantity | number | null | No | — |
inventory[].availability | string | No | — |
inventory[].purchasable | boolean | No | — |
const shop = window.Portal.commerce.create('STORE_REF');
await shop.init();
const cart = await shop.cart();
if (cart !== null) {
console.log(cart.line_count, 'items,', cart.total_cents / 100);
}PortalCommerceCartLine
One line of the cart.
| Name | Type | Required | Description |
|---|---|---|---|
id | number | Yes | The line id; pass it to updateLine() / removeLine() / saveLineForLater(). |
variant_ref | string | No | The variant bought. |
product_ref | string | No | The product it belongs to. |
product_name | string | Yes | The product's name. |
variant_title | string | Yes | The variant's title, for example 'Blue / M'. |
direct_payment_item_reference_num | string | null | No | The Direct Payments item the price comes from. |
quantity | number | Yes | Units on the line. |
unit_price_cents | number | Yes | Price of one unit in cents. |
line_subtotal_cents | number | Yes | unit_price_cents * quantity. |
custom_attributes | Record<string, unknown> | No | The buyer's choices stored on the line. |
available_quantity | number | null | No | Units in stock, or null when unlimited. |
availability | string | No | The stock state, for example 'in_stock'. |
purchasable | boolean | No | False when the line can no longer be bought (sold out, removed). |
hold_active | boolean | No | True while stock is being held for this cart. |
hold_expires_at | string | null | No | ISO time the stock hold ends. |
rental | PortalCommerceRentalLine | null | No | 06: set on rental lines only. |
PortalCommerceCheckoutBeginResult
The answer to shop.checkout.begin().
| Name | Type | Required | Description |
|---|---|---|---|
cart | PortalCommerceCart | Yes | The cart, re-priced for checkout. |
direct_payment | string | null | Yes | The Direct Payment the shopper pays on. |
shipping_item_ref | string | null | Yes | The Direct Payments item representing shipping on the invoice. |
discount_item_ref | string | null | Yes | The Direct Payments item representing the discount on the invoice. |
checkout_recipe | object | No | What the invoice must contain; build the invoice from it and send hash to complete(). |
checkout_recipe.hash | string | Yes | Proof of the recipe; send it back as recipe_hash. |
checkout_recipe.expected_total_cents | number | Yes | The total the invoice must come to, in cents. |
checkout_recipe.expires_at | string | Yes | ISO time after which the recipe is stale. |
checkout_recipe.lines | Array<object> | Yes | The invoice lines, one per Direct Payments item to add (invoice.addItem()). amount_cents is the per-unit price for a dynamically priced item (shipping, discounts); absent for a fixed item, which Direct Payments prices itself. |
changes | Array<Record<string, unknown>> | Yes | Things that changed since the shopper last saw the cart (price, stock). |
PortalCommerceCheckoutConfirmResult
The answer to shop.checkout.complete().
| Name | Type | Required | Description |
|---|---|---|---|
order_reference_num | string | Yes | The order's reference. |
order_number | string | Yes | The order number shown to the shopper. |
held | boolean | No | True when the order is held (for example awaiting review). |
PortalCommerceEventName
The events shop.on() / shop.off() understand. Never fetch the cart inside a cart:updated listener: the payload already is the cart.
One of:
cart:updatedinventory:updatedcheckout:changedorder:placedprices:updatedfavorites:updated
PortalCommerceFavorite
A product the shopper marked as a favourite.
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The product's reference. |
name | string | Yes | The product's name. |
slug | string | null | No | URL slug. |
short_description | string | null | No | A one-line description. |
currency | string | Yes | ISO currency code. |
direct_payment_item_reference_num | string | null | No | The Direct Payments item the price comes from. |
availability | string | No | The stock state. |
purchasable | boolean | No | False when the product can no longer be bought. |
default_variant_ref | string | null | No | The variant to add when the shopper buys it straight from the favourites list. |
is_favorite | boolean | No | Always true in the favourites list; present on products flagged elsewhere. |
PortalCommerceListPage
One page of a cursor-paged product list.
| Name | Type | Required | Description |
|---|---|---|---|
products | T[] | Yes | The products of this page. |
pageSize | number | Yes | The page size used. |
nextCursor | string | null | Yes | Pass as the cursor to get the next page. |
hasMore | boolean | Yes | True when a next page exists. |
PortalCommercePricedProduct
A product with its Direct Payments price joined on (see attachPricing()). dynamic is set for a DYNAMIC item: the shopper chooses an amount between min and max.
The type T plus these fields:
| Name | Type | Required | Description |
|---|---|---|---|
price_cents | number | Yes | Price in cents (0 when no item was found). |
tax_cents | number | Yes | Tax in cents. |
dynamic | object | Yes | The allowed amount range for a DYNAMIC item, else null. |
dynamic.min | number | Yes | — |
dynamic.max | number | Yes | The largest length allowed. |
purchasable | boolean | Yes | False when the price could not be resolved. |
price_adjustments | Array<Record<string, unknown>> | No | Price adjustments applied (sales, markets). |
PortalCommerceProductQuery
Filters and paging for catalogue reads (shop.catalog.products(), productsPage(), Portal.commerce.getProducts()).
| Name | Type | Required | Description |
|---|---|---|---|
category | string | No | Only products of this category (slug or reference). |
page | number | No | 1-based page number. |
limit | number | No | Page size. |
store | string | No | The store reference, when the call is not made through a store instance. |
search | string | No | Free-text filter on the product name. For ranked search use shop.search.search(). |
sort | string | No | Sort order key, for example 'price_asc'. |
include_images | boolean | No | Include image addresses with each product. |
PortalCommercePurchaseView
What an invoice paid for, as the store sees it (shop.account.purchase()).
| Name | Type | Required | Description |
|---|---|---|---|
status | string | Yes | Payment status. |
paid | boolean | Yes | True when it is paid. |
amount_cents | number | Yes | Amount in cents. |
currency | string | Yes | ISO currency code. |
charge_id | string | null | Yes | The provider's charge id. |
refunded_cents | number | Yes | Cents refunded. |
lines | object[] | Yes | The purchased lines. |
lines[].item_ref | string | Yes | The Direct Payments item reference. |
lines[].name | string | Yes | The name. |
lines[].quantity | number | Yes | How many. |
lines[].unit_cents | number | Yes | — |
lines[].tax_cents | number | Yes | — |
PortalCommerceRecommendationsResult
One recommendation set.
| Name | Type | Required | Description |
|---|---|---|---|
kind | string | Yes | The kind asked for. |
hits | Array<Record<string, unknown>> | Yes | The recommended products. |
PortalCommerceRentalAvailability
The answer to rentalAvailability(): the rules and the per-day free units of a rental variant.
| Name | Type | Required | Description |
|---|---|---|---|
variant_ref | string | Yes | The variant. |
min_days | number | Yes | Shortest rental allowed, in days. |
max_days | number | null | Yes | Longest rental allowed, or null for no limit. |
max_days_ahead | number | Yes | How far ahead a rental can start, in days. |
rental_item_reference_num | string | Yes | The per-day price item. |
deposit_item_reference_num | string | null | Yes | The deposit item, or null. |
day_price_cents | number | null | Yes | Price per day in cents, or null when not priced. |
deposit_cents | number | null | Yes | Deposit in cents, or null. |
days | PortalCommerceRentalDay[] | Yes | The requested days. |
PortalCommerceRentalDates
Custom-attribute keys a rental add-to-cart sends (YYYY-MM-DD).
| Name | Type | Required | Description |
|---|---|---|---|
rental_starts_on | string | Yes | First rental day. |
rental_ends_on | string | Yes | Last rental day (inclusive). |
PortalCommerceRentalDay
One day of a rental variant's availability calendar.
| Name | Type | Required | Description |
|---|---|---|---|
date | string | Yes | The day, YYYY-MM-DD. |
available | number | null | Yes | Units free that day; null = unlimited. |
PortalCommerceRentalLine
A rental cart line's dates and Direct Payments items. Dates are inclusive (10th to 12th = 3 days); the invoice carries the per-day item x rental_quantity (units x days) and the deposit item x units.
| Name | Type | Required | Description |
|---|---|---|---|
starts_on | string | Yes | First rental day, YYYY-MM-DD. |
ends_on | string | Yes | Last rental day, YYYY-MM-DD (inclusive). |
days | number | Yes | Number of rental days. |
rental_item_reference_num | string | Yes | The per-day price item. |
rental_quantity | number | Yes | Units x days, the quantity of the rental item on the invoice. |
deposit_item_reference_num | string | null | Yes | The deposit item, or null when there is no deposit. |
deposit_unit_cents | number | null | Yes | Deposit per unit in cents. |
deposit_cents | number | Yes | Total deposit of the line in cents. |
PortalCommerceSavedItem
A cart line the shopper put aside ("save for later").
| Name | Type | Required | Description |
|---|---|---|---|
id | number | Yes | The saved item's id; pass it to moveSavedToCart() / removeSaved(). |
variant_ref | string | No | The variant saved. |
product_ref | string | No | The product it belongs to. |
product_slug | string | null | No | The product's URL slug. |
product_name | string | Yes | The product's name. |
variant_title | string | Yes | The variant's title. |
quantity | number | Yes | Units saved. |
unit_price_cents | number | Yes | Price of one unit in cents. |
custom_attributes | Record<string, unknown> | No | The buyer's choices stored on the item. |
available_quantity | number | null | No | Units in stock, or null when unlimited. |
availability | string | No | The stock state. |
purchasable | boolean | No | False when the item can no longer be bought. |
PortalCommerceSearchOptions
Options of shop.search.search().
| Name | Type | Required | Description |
|---|---|---|---|
sort | string | No | Sort order key. |
cursor | string | No | The cursor of the previous result, to get the next page. |
limit | number | No | Page size. |
filters | Record<string, unknown> | No | Facet filters, for example { color: ['red'] }. |
PortalCommerceSearchResult
The answer to a search.
| Name | Type | Required | Description |
|---|---|---|---|
hits | Array<Record<string, unknown>> | Yes | The matching products. |
facets | Record<string, unknown> | No | Counts per filter value, to draw the filter sidebar. |
total | number | Yes | Total matches. |
cursor | string | null | No | Pass to the next call for the next page; null/absent at the end. |
corrected_query | string | null | No | The spelling the engine searched for instead, when it corrected the query. |
PortalCommerceSuggestResult
The answer to shop.search.suggest().
| Name | Type | Required | Description |
|---|---|---|---|
suggestions | string[] | Yes | Completions of the typed prefix. |
PortalReturnRequest
The shopper-facing shape (no admin_note/decided_by, which are admin-only).
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The request's reference. |
order_reference_num | string | Yes | The order it is about. |
store_reference_num | string | Yes | The store the order is from. |
kind | 'return' | 'cancellation' | Yes | A return of goods, or a cancellation of an order. |
status | string | Yes | Where the request stands. One of requested, approved, rejected, received, refunded, cancelled. |
reason | string | Yes | The shopper's reason. |
note | string | null | No | The shopper's note. |
lines | object[] | Yes | The order lines and quantities involved. |
lines[].order_line_id | number | Yes | — |
lines[].quantity | number | Yes | How many. |
resolution | string | null | No | How it was resolved (refund, exchange...). |
refund_cents | number | null | No | Cents refunded. |
decided_at | string | null | No | ISO time the store decided. |
created_at | string | null | No | ISO creation time. |