Skip to content

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 ​

ts
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)

ts
const account = shop.account;

attachPricing() ​

Alias of catalog.attachPricing().

ts
const result = shop.attachPricing(products, dpItems);

Parameters

NameTypeRequiredDescription
productsT[]YesThe products.
dpItemsReadonlyArray<PortalDirectPaymentItem | Record<string, unknown>>YesOne 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)

ts
const b2b = shop.b2b;

beginCheckout() ​

Alias of checkout.begin().

ts
const checkoutBeginResult = await shop.beginCheckout(email);

Parameters

NameTypeRequiredDescription
emailstringNoAn 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)

ts
const cart = shop.cart;

catalog ​

Catalogue reads.

Type: PortalCommerceCatalogFacet (read-only)

ts
const catalog = shop.catalog;

checkout ​

Checkout.

Type: PortalCommerceCheckoutFacet (read-only)

ts
const checkout = shop.checkout;

completeCheckout() ​

Alias of checkout.complete().

ts
const checkoutConfirmResult = await shop.completeCheckout(payload);

Parameters

NameTypeRequiredDescription
payloadobjectYesThe data to send.
payload.invoice_refstringYes—
payload.direct_payment_refstringYes—
payload.processor_refstringYes—
payload.cart_refstringYes—
payload.linesobject[]YesThe lines involved.
payload.lines[].item_refstringYesThe Direct Payments item reference.
payload.lines[].namestringYesThe name.
payload.lines[].quantitynumberYesHow many.
payload.recipe_hashstringNo—

Returns

Resolves with a PortalCommerceCheckoutConfirmResult: The answer to shop.checkout.complete().

Privacy consent.

Type: PortalCommerceConsentFacet (read-only)

ts
const consent = shop.consent;

eachProductPage() ​

Pages through the catalogue: for await (const page of shop.eachProductPage(query, maxPages)).

ts
const result = shop.eachProductPage(query, maxPages);

Parameters

NameTypeRequiredDescription
queryPortalCommerceProductQueryYesFilters and paging for catalogue reads (shop.catalog.products(), productsPage(), Portal.commerce.getProducts()).
maxPagesnumberYes—

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.

ts
const result = await shop.init();

Returns

Resolves with the server's record as a plain object.

listSubscriptions() ​

Alias of subscriptions.list().

ts
const result = await shop.listSubscriptions();

Returns

Resolves with Array<Record<string, unknown>>.

marketplace ​

Multi-vendor features.

Type: PortalCommerceMarketplaceFacet (read-only)

ts
const marketplace = shop.marketplace;

off() ​

Stops listening.

ts
shop.off(event, listener);

Parameters

NameTypeRequiredDescription
eventPortalCommerceEventNameYesThe events shop.on() / shop.off() understand.
listener(payload: unknown) => voidYesFunction called when it happens.

on() ​

Listens for a store event; the payload depends on the event (cart:updated carries the cart).

ts
shop.on(event, listener);

Parameters

NameTypeRequiredDescription
eventPortalCommerceEventNameYesThe events shop.on() / shop.off() understand.
listener(payload: unknown) => voidYesFunction called when it happens.

products() ​

Alias of catalog.products().

ts
const result = await shop.products(query);

Parameters

NameTypeRequiredDescription
queryPortalCommerceProductQueryNoFilters 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 }.

ts
const rentalAvailability = await shop.rentalAvailability(variantRef, from, to);

Parameters

NameTypeRequiredDescription
variantRefstringYesThe variant's reference.
fromstringYesThe start of the range.
tostringYesThe 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)

ts
const reviews = shop.reviews;

Search and recommendations.

Type: PortalCommerceSearchFacet (read-only)

ts
const search = shop.search;

subjectKey() ​

The shopper's anonymous consent key (stored in the browser).

ts
const value = shop.subjectKey();

Returns

Returns a string.

subscriptions ​

Product subscriptions.

Type: PortalCommerceSubscriptionsFacet (read-only)

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

ts
const result = await shop.account.balances(ownerRef);

Parameters

NameTypeRequiredDescription
ownerRefstringYes—

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
accountsArray<Record<string, unknown>>Yes—

cancelOrder() ​

Cancels an order that has not shipped.

ts
const result = await shop.account.cancelOrder(referenceNum, reason);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.
reasonstringNo—

Returns

Resolves with the server's record as a plain object.

cancelReturn() ​

Withdraws a return request.

ts
await shop.account.cancelReturn(referenceNum);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.

Returns

Resolves when the call has completed.

order() ​

One order.

ts
const result = await shop.account.order(referenceNum);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe 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.

ts
const result = await shop.account.orderLookup(number, email);

Parameters

NameTypeRequiredDescription
numberstringYesThe order number shown to the shopper.
emailstringYesAn 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.

ts
const result = await shop.account.orders(opts);

Parameters

NameTypeRequiredDescription
optsobjectNoOptional settings.
opts.scope'open' | 'all'NoWhich records to include.
opts.limitnumberNoThe most items to return.
opts.cursorstringNoThe 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.

ts
const result = await shop.account.orderUpsell(orderReferenceNum, variantRef, quantity);

Parameters

NameTypeRequiredDescription
orderReferenceNumstringYesThe order's reference number.
variantRefstringYesThe variant's reference.
quantitynumberNoHow 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).

ts
const purchaseView = await shop.account.purchase(invoiceRef);

Parameters

NameTypeRequiredDescription
invoiceRefstringYesThe 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.

ts
const result = await shop.account.requestExchange(orderReferenceNum, payload);

Parameters

NameTypeRequiredDescription
orderReferenceNumstringYesThe order's reference number.
payloadRecord<string, unknown>YesThe data to send.

Returns

Resolves with the server's record as a plain object.

requestReturn() ​

Asks to return items from an order.

ts
const result = await shop.account.requestReturn(orderReferenceNum, payload);

Parameters

NameTypeRequiredDescription
orderReferenceNumstringYesThe order's reference number.
payloadobjectYesThe data to send.
payload.reasonstringYes—
payload.notestringNo—
payload.linesobject[]YesThe lines involved.
payload.lines[].order_line_idnumberYes—
payload.lines[].quantitynumberYesHow 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.

ts
const result = await shop.account.returnEligibility(orderReferenceNum);

Parameters

NameTypeRequiredDescription
orderReferenceNumstringYesThe order's reference number.

Returns

Resolves with the server's record as a plain object.

returnLabel() ​

The prepaid return label of an approved return.

ts
const result = await shop.account.returnLabel(returnReferenceNum);

Parameters

NameTypeRequiredDescription
returnReferenceNumstringYes—

Returns

Resolves with the server's record as a plain object.

returns() ​

The shopper's return requests.

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

ts
await shop.account.subscribeAlert(payload);

Parameters

NameTypeRequiredDescription
payloadobjectYesThe data to send.
payload.variant_reference_numstringYes—
payload.emailstringYesAn e-mail address.

Returns

Resolves when the call has completed.

track() ​

Shipment tracking for an order, by number and email.

ts
const result = await shop.account.track(number, email);

Parameters

NameTypeRequiredDescription
numberstringYesThe order number shown to the shopper.
emailstringYesAn 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.

ts
const result = await shop.b2b.payOnTerms(companyId, netDays);

Parameters

NameTypeRequiredDescription
companyIdnumberYesThe company account's id.
netDaysnumberYesPay 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.

ts
const result = await shop.b2b.quickOrder(rows);

Parameters

NameTypeRequiredDescription
rowsobject[]YesA list of objects, described below.
rows[].skustringYesYour stock-keeping code.
rows[].quantitynumberYesHow 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.

ts
const result = await shop.b2b.requestApproval(cartRef, approverGroup);

Parameters

NameTypeRequiredDescription
cartRefstringYesThe cart's reference.
approverGroupstringNo—

Returns

Resolves with the server's record as a plain object.

requestQuote() ​

Asks for a quote for some lines.

ts
const result = await shop.b2b.requestQuote(lines, email);

Parameters

NameTypeRequiredDescription
linesArray<Record<string, unknown>>YesThe lines involved.
emailstringNoAn e-mail address.

Returns

Resolves with the server's record as a plain object.

respondQuote() ​

Accepts, declines or counters a quote.

ts
const result = await shop.b2b.respondQuote(referenceNum, action, lines);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.
action'accept' | 'decline' | 'counter'YesThe action.
linesArray<Record<string, unknown>>NoThe 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.

ts
const result = await shop.cart();

Returns

Resolves with PortalCommerceCart \| null.

add() ​

Adds a variant to the cart (creating the cart if needed).

ts
const cart = await shop.cart.add(input);

Parameters

NameTypeRequiredDescription
inputPortalCommerceAddToCartInputYesWhat 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.

ts
const commerceFavorites = await shop.cart.addFavorite(productRef);

Parameters

NameTypeRequiredDescription
productRefstringYesThe product's reference.

Returns

Resolves with an array of PortalCommerceFavorite.

applyCredit() ​

Uses the shopper's store credit (in cents) on the cart.

ts
const result = await shop.cart.applyCredit(cents);

Parameters

NameTypeRequiredDescription
centsnumberYes—

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
value_stateRecord<string, unknown>YesThe gift-card or credit balance state.

applyDiscount() ​

Applies a discount code. Rejects when the code is not valid.

ts
const cart = await shop.cart.applyDiscount(code);

Parameters

NameTypeRequiredDescription
codestringYesThe 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.

ts
const result = await shop.cart.applyGiftCard(code);

Parameters

NameTypeRequiredDescription
codestringYesThe code to apply.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
value_stateRecord<string, unknown>YesThe gift-card or credit balance state.

cart() ​

Same as calling the facet: await shop.cart().

ts
const result = await shop.cart.cart();

Returns

Resolves with PortalCommerceCart \| null.

favorites() ​

The shopper's favourite products.

ts
const commerceFavorites = await shop.cart.favorites();

Returns

Resolves with an array of PortalCommerceFavorite.

moveSavedToCart() ​

Moves a saved item back into the cart.

ts
const cart = await shop.cart.moveSavedToCart(savedId);

Parameters

NameTypeRequiredDescription
savedIdnumberYesThe 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).

ts
const result = await shop.cart.quickOrder(rows);

Parameters

NameTypeRequiredDescription
rowsobject[]YesA list of objects, described below.
rows[].skustringYesYour stock-keeping code.
rows[].quantitynumberYesHow 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.

ts
const result = await shop.cart.recover(token);

Parameters

NameTypeRequiredDescription
tokenstringYesA token issued by the server (see the description above).

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
cartPortalCommerceCartYes—

removeDiscount() ​

Removes the applied discount code.

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

ts
const commerceFavorites = await shop.cart.removeFavorite(productRef);

Parameters

NameTypeRequiredDescription
productRefstringYesThe product's reference.

Returns

Resolves with an array of PortalCommerceFavorite.

removeLine() ​

Removes a line.

ts
const cart = await shop.cart.removeLine(lineId);

Parameters

NameTypeRequiredDescription
lineIdnumberYesThe cart line's id.

Returns

Resolves with a PortalCommerceCart: The shopper's cart as the server computes it.

removeSaved() ​

Deletes a saved item.

ts
const cart = await shop.cart.removeSaved(savedId);

Parameters

NameTypeRequiredDescription
savedIdnumberYesThe 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".

ts
const cart = await shop.cart.saveLineForLater(lineId);

Parameters

NameTypeRequiredDescription
lineIdnumberYesThe 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).

ts
const result = await shop.cart.setBusinessTaxId(businessTaxId);

Parameters

NameTypeRequiredDescription
businessTaxIdstringYes—

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
business_tax_idstring | nullYes—
validboolean | nullYesTrue 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.

ts
const cart = await shop.cart.setShippingAddress(address);

Parameters

NameTypeRequiredDescription
addressRecord<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.

ts
const cart = await shop.cart.setShippingMethod(shippingMethodId);

Parameters

NameTypeRequiredDescription
shippingMethodIdnumber | nullYesThe 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.

ts
const result = await shop.cart.shippingMethods();

Returns

Resolves with Array<Record<string, unknown>>.

updateLine() ​

Sets a line's quantity (0 removes it).

ts
const cart = await shop.cart.updateLine(lineId, quantity);

Parameters

NameTypeRequiredDescription
lineIdnumberYesThe cart line's id.
quantitynumberYesHow 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.

ts
const result = shop.catalog.attachPricing(products, dpItems);

Parameters

NameTypeRequiredDescription
productsT[]YesThe products.
dpItemsReadonlyArray<PortalDirectPaymentItem | Record<string, unknown>>YesdpItems 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

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

ts
const result = await shop.catalog.categories();

Returns

Resolves with unknown.

collections() ​

The curated collections.

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

ts
const result = await shop.catalog.markets();

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
marketsArray<Record<string, unknown>>Yes—
currentstringNo—

product() ​

One product by slug or reference, with its variants.

ts
const result = await shop.catalog.product(slugOrRef);

Parameters

NameTypeRequiredDescription
slugOrRefstringYesThe product's slug or reference.

Returns

Resolves with unknown.

productImages() ​

The images of a product (slug or reference): { images: [address,...] }.

ts
const result = await shop.catalog.productImages(slugOrRef);

Parameters

NameTypeRequiredDescription
slugOrRefstringYesThe product's slug or reference.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
imagesstring[]Yes—

products() ​

One page of products (see productsPage() for the typed, cursor-based variant).

ts
const result = await shop.catalog.products(query);

Parameters

NameTypeRequiredDescription
queryPortalCommerceProductQueryNoFilters 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 }.

ts
const result = await shop.catalog.productsPage(query);

Parameters

NameTypeRequiredDescription
queryPortalCommerceProductQueryNoFilters 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).

ts
const rentalAvailability = await shop.catalog.rentalAvailability(variantRef, from, to);

Parameters

NameTypeRequiredDescription
variantRefstringYesThe variant's reference.
fromstringYesThe start of the range.
tostringYesThe 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.

ts
const result = await shop.catalog.setMarket(marketRef);

Parameters

NameTypeRequiredDescription
marketRefstringYes—

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.

ts
const result = await shop.catalog.variantFor(productRef, options);

Parameters

NameTypeRequiredDescription
productRefstringYesThe product's reference.
optionsRecord<string, string>YesOptional 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.

ts
await shop.checkout.abort();

Returns

Resolves when the call has completed.

addresses() ​

The signed-in shopper's saved addresses.

ts
const result = await shop.checkout.addresses();

Returns

Resolves with Array<Record<string, unknown>>.

addressSuggest() ​

Address completion while the shopper types.

ts
const result = await shop.checkout.addressSuggest(query);

Parameters

NameTypeRequiredDescription
querystringYesFilters 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.

ts
await shop.checkout.attach(cartRef, invoiceRef, recipeHash);

Parameters

NameTypeRequiredDescription
cartRefstringYesThe cart's reference.
invoiceRefstringYesThe invoice's reference.
recipeHashstringNoPass 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.

ts
const checkoutBeginResult = await shop.checkout.begin(email);

Parameters

NameTypeRequiredDescription
emailstringNoAn 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.

ts
const cart = await shop.checkout.buyAgain(orderReferenceNum);

Parameters

NameTypeRequiredDescription
orderReferenceNumstringYesThe 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.

ts
const checkoutConfirmResult = await shop.checkout.complete(payload);

Parameters

NameTypeRequiredDescription
payloadobjectYesThe data to send.
payload.invoice_refstringYesThe paid invoice.
payload.direct_payment_refstringYesThe Direct Payment it was paid on.
payload.processor_refstringYesThe processor that took the payment.
payload.cart_refstringYesThe cart being converted.
payload.linesobject[]YesThe invoice lines.
payload.lines[].item_refstringYesThe Direct Payments item reference.
payload.lines[].namestringYesThe name.
payload.lines[].quantitynumberYesHow many.
payload.recipe_hashstringNocheckout_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.

ts
await shop.checkout.convertGuest(orderReferenceNum);

Parameters

NameTypeRequiredDescription
orderReferenceNumstringYesThe 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.

ts
const result = await shop.checkout.express(payload);

Parameters

NameTypeRequiredDescription
payloadobjectYesThe data to send.
payload.contactRecord<string, unknown>No—
payload.shipping_addressRecord<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.

ts
const cart = await shop.checkout.extras(payload);

Parameters

NameTypeRequiredDescription
payloadRecord<string, unknown>YesThe 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).

ts
const result = await shop.checkout.methods(country, amountCents);

Parameters

NameTypeRequiredDescription
countrystringYesAn ISO country code.
amountCentsnumberYesAn amount in cents.

Returns

Resolves with Array<Record<string, unknown>>.

paymentFailed() ​

Tells the store the payment for a cart failed (starts recovery e-mails).

ts
const result = await shop.checkout.paymentFailed(cartRef);

Parameters

NameTypeRequiredDescription
cartRefstringYesThe 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.

ts
const result = await shop.checkout.payOnTerms(companyId, netDays);

Parameters

NameTypeRequiredDescription
companyIdnumberYesThe company account's id.
netDaysnumberYesB2B: 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.

ts
const result = await shop.checkout.saveAddress(payload);

Parameters

NameTypeRequiredDescription
payloadobjectYesThe data to send.
payload.labelstringNo—
payload.addressRecord<string, unknown>Yes—
payload.is_defaultbooleanNo—

Returns

Resolves with the server's record as a plain object.

state() ​

The state of the checkout in progress.

ts
const result = await shop.checkout.state();

Returns

Resolves with the server's record as a plain object.

upsell() ​

Adds an upsell variant during checkout.

ts
const result = await shop.checkout.upsell(variantRef, quantity);

Parameters

NameTypeRequiredDescription
variantRefstringYesThe variant's reference.
quantitynumberNoHow 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).

ts
const ok = shop.consent.allows(purpose);

Parameters

NameTypeRequiredDescription
purposestringYesWhat 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).

ts
await shop.consent.load();

Returns

Resolves when the call has completed.

set() ​

Records the shopper's choice for analytics or marketing e-mail.

ts
await shop.consent.set(purpose, granted);

Parameters

NameTypeRequiredDescription
purpose'analytics' | 'marketing_email'YesWhat the sign-in is for.
grantedbooleanYes—

Returns

Resolves when the call has completed.

subjectKey() ​

The anonymous key this shopper's consent is stored under.

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

ts
await shop.marketplace.apply(body);

Parameters

NameTypeRequiredDescription
bodyobjectYesThe text of the message.
body.namestringYesThe name.
body.emailstringYesAn e-mail address.
body.biostringNo—

Returns

Resolves when the call has completed.

vendor() ​

One vendor by slug.

ts
const result = await shop.marketplace.vendor(slug);

Parameters

NameTypeRequiredDescription
slugstringYesThe URL slug.

Returns

Resolves with the server's record as a plain object.

vendorProducts() ​

The products of one vendor.

ts
const result = await shop.marketplace.vendorProducts(slug);

Parameters

NameTypeRequiredDescription
slugstringYesThe URL slug.

Returns

Resolves with Array<Record<string, unknown>>.

vendors() ​

The vendors of the marketplace.

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

ts
const result = await shop.reviews.ask(payload);

Parameters

NameTypeRequiredDescription
payloadobjectYesThe data to send.
payload.product_reference_numstringYes—
payload.bodystringYesThe text of the message.
payload.asker_namestringNo—

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
reference_numstringYesThe record's reference number.
statusstringYesThe status word.

eligibility() ​

Whether this person may review this order line.

ts
const result = await shop.reviews.eligibility(productRef, orderLineId, siteUserRef);

Parameters

NameTypeRequiredDescription
productRefstringYesThe product's reference.
orderLineIdnumberYes—
siteUserRefstringYesThe site user's reference.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
eligiblebooleanYes—

list() ​

The approved reviews of a product.

ts
const result = await shop.reviews.list(productRef);

Parameters

NameTypeRequiredDescription
productRefstringYesThe product's reference.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
reviewsArray<Record<string, unknown>>YesThe reviews.

questions() ​

The questions asked about a product.

ts
const result = await shop.reviews.questions(productRef);

Parameters

NameTypeRequiredDescription
productRefstringYesThe product's reference.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
questionsArray<Record<string, unknown>>Yes—

submit() ​

Submits a review (rating 1-5); it may wait for moderation (status).

ts
const result = await shop.reviews.submit(payload);

Parameters

NameTypeRequiredDescription
payloadobjectYesThe data to send.
payload.order_line_idnumberYes—
payload.site_user_referencestringYes—
payload.ratingnumberYesA rating from 1 to 5.
payload.bodystringYesThe text of the message.
payload.author_namestringNo—

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
reference_numstringYesThe record's reference number.
statusstringYesThe status word.

vote() ​

Votes a review helpful or not.

ts
await shop.reviews.vote(referenceNum, helpful);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.
helpfulbooleanYes—

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.

ts
const searchResult = await shop.search.facets(query);

Parameters

NameTypeRequiredDescription
querystringYesFilters and options.

Returns

Resolves with a PortalCommerceSearchResult: The answer to a search.

recentlyViewed() ​

The products this shopper looked at recently.

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

ts
const result = await shop.search.recommendations(kind, productRef);

Parameters

NameTypeRequiredDescription
kindstringYes—
productRefstringNoThe product's reference.

Returns

Resolves with Array<Record<string, unknown>>.

Searches the catalogue.

ts
const searchResult = await shop.search.search(query, options);

Parameters

NameTypeRequiredDescription
querystringYesFilters and options.
optionsPortalCommerceSearchOptionsNoOptions of shop.search.search().

Returns

Resolves with a PortalCommerceSearchResult: The answer to a search.

suggest() ​

Completions for a search box as the shopper types.

ts
const suggestResult = await shop.search.suggest(prefix);

Parameters

NameTypeRequiredDescription
prefixstringYes—

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()).

ts
await shop.subscriptions.cancel(subscriptionRef);

Parameters

NameTypeRequiredDescription
subscriptionRefstringYesThe subscription's reference.

Returns

Resolves when the call has completed.

list() ​

The shopper's subscriptions.

ts
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).

ts
await shop.subscriptions.pause(subscriptionRef);

Parameters

NameTypeRequiredDescription
subscriptionRefstringYesThe subscription's reference.

Returns

Resolves when the call has completed.

setBox() ​

Chooses the items of a subscription box.

ts
await shop.subscriptions.setBox(subscriptionRef, boxSelection);

Parameters

NameTypeRequiredDescription
subscriptionRefstringYesThe subscription's reference.
boxSelectionstring[]Yes—

Returns

Resolves when the call has completed.

setFrequency() ​

Not available yet: rejects.

ts
await shop.subscriptions.setFrequency(subscriptionRef, tierRef);

Parameters

NameTypeRequiredDescription
subscriptionRefstringYesThe subscription's reference.
tierRefstringYesThe tier's reference.

Returns

Resolves when the call has completed.

skip() ​

Skips the next delivery.

ts
await shop.subscriptions.skip(subscriptionRef);

Parameters

NameTypeRequiredDescription
subscriptionRefstringYesThe subscription's reference.

Returns

Resolves when the call has completed.

swap() ​

Swaps the product of a subscription.

ts
await shop.subscriptions.swap(subscriptionRef, payload);

Parameters

NameTypeRequiredDescription
subscriptionRefstringYesThe subscription's reference.
payloadRecord<string, unknown>YesThe 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).

ts
const instance = window.Portal.commerce.create(storeRef);

Parameters

NameTypeRequiredDescription
storeRefstringYesThe 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.

ts
const result = await window.Portal.commerce.getCategories(store);

Parameters

NameTypeRequiredDescription
storestringNoThe store's reference.

Returns

Resolves with unknown.

getProducts() ​

Reads products without a store instance (pass query.store).

ts
const result = await window.Portal.commerce.getProducts(query);

Parameters

NameTypeRequiredDescription
queryPortalCommerceProductQueryNoFilters and paging for catalogue reads (shop.catalog.products(), productsPage(), Portal.commerce.getProducts()).

Returns

Resolves with unknown.

Types ​

PortalCommerceAddToCartInput ​

What shop.cart.add() sends.

NameTypeRequiredDescription
variant_refstringYesThe variant (the exact buyable version of a product) to add.
quantitynumberNoHow many; default 1.
custom_attributesRecord<string, unknown>NoBuyer 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.

NameTypeRequiredDescription
reference_numstringYesThe cart's reference.
store_reference_numstringYesThe store it belongs to.
currencystringYesISO currency code.
statusstringYesopen, checkout, converted...
emailstring | nullNoThe shopper's e-mail once known.
shipping_method_idnumber | nullNoThe chosen shipping method id, or null.
requires_shippingbooleanNoTrue when the cart contains something that must be shipped.
discount_codestring | nullNoThe discount code applied.
promotion_codestring | nullNoThe promotion code applied.
promotion_messagesstring[]NoMessages about promotions ("add $5 for free shipping").
free_shippingbooleanNoTrue when a promotion makes shipping free.
linesPortalCommerceCartLine[]YesThe lines.
line_countnumberYesNumber of lines.
subtotal_centsnumberYesSum of the lines in cents.
discount_centsnumberYesDiscounts in cents (positive number taken off).
shipping_centsnumberYesShipping in cents.
tax_centsnumberYesTax in cents.
deposit_centsnumberNo06: rental deposits (their own Direct Payments item), included in total_cents.
total_centsnumberYesWhat the shopper pays, in cents.
show_quantitybooleanNoStore setting: show quantity controls.
allow_save_for_laterbooleanNoStore setting: offer "save for later".
allow_favoritesbooleanNoStore setting: offer favourites.
saved_for_laterPortalCommerceSavedItem[]NoLines saved for later.
cart_hold_minutesnumberNoHow long stock is held for the cart, in minutes.
inventoryobject[]NoLive stock of the cart's products.
inventory[].product_refstringNo—
inventory[].variant_refstringNo—
inventory[].available_quantitynumber | nullNo—
inventory[].availabilitystringNo—
inventory[].purchasablebooleanNo—
ts
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.

NameTypeRequiredDescription
idnumberYesThe line id; pass it to updateLine() / removeLine() / saveLineForLater().
variant_refstringNoThe variant bought.
product_refstringNoThe product it belongs to.
product_namestringYesThe product's name.
variant_titlestringYesThe variant's title, for example 'Blue / M'.
direct_payment_item_reference_numstring | nullNoThe Direct Payments item the price comes from.
quantitynumberYesUnits on the line.
unit_price_centsnumberYesPrice of one unit in cents.
line_subtotal_centsnumberYesunit_price_cents * quantity.
custom_attributesRecord<string, unknown>NoThe buyer's choices stored on the line.
available_quantitynumber | nullNoUnits in stock, or null when unlimited.
availabilitystringNoThe stock state, for example 'in_stock'.
purchasablebooleanNoFalse when the line can no longer be bought (sold out, removed).
hold_activebooleanNoTrue while stock is being held for this cart.
hold_expires_atstring | nullNoISO time the stock hold ends.
rentalPortalCommerceRentalLine | nullNo06: set on rental lines only.

PortalCommerceCheckoutBeginResult ​

The answer to shop.checkout.begin().

NameTypeRequiredDescription
cartPortalCommerceCartYesThe cart, re-priced for checkout.
direct_paymentstring | nullYesThe Direct Payment the shopper pays on.
shipping_item_refstring | nullYesThe Direct Payments item representing shipping on the invoice.
discount_item_refstring | nullYesThe Direct Payments item representing the discount on the invoice.
checkout_recipeobjectNoWhat the invoice must contain; build the invoice from it and send hash to complete().
checkout_recipe.hashstringYesProof of the recipe; send it back as recipe_hash.
checkout_recipe.expected_total_centsnumberYesThe total the invoice must come to, in cents.
checkout_recipe.expires_atstringYesISO time after which the recipe is stale.
checkout_recipe.linesArray<object>YesThe 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.
changesArray<Record<string, unknown>>YesThings that changed since the shopper last saw the cart (price, stock).

PortalCommerceCheckoutConfirmResult ​

The answer to shop.checkout.complete().

NameTypeRequiredDescription
order_reference_numstringYesThe order's reference.
order_numberstringYesThe order number shown to the shopper.
heldbooleanNoTrue 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:updated
  • inventory:updated
  • checkout:changed
  • order:placed
  • prices:updated
  • favorites:updated

PortalCommerceFavorite ​

A product the shopper marked as a favourite.

NameTypeRequiredDescription
reference_numstringYesThe product's reference.
namestringYesThe product's name.
slugstring | nullNoURL slug.
short_descriptionstring | nullNoA one-line description.
currencystringYesISO currency code.
direct_payment_item_reference_numstring | nullNoThe Direct Payments item the price comes from.
availabilitystringNoThe stock state.
purchasablebooleanNoFalse when the product can no longer be bought.
default_variant_refstring | nullNoThe variant to add when the shopper buys it straight from the favourites list.
is_favoritebooleanNoAlways true in the favourites list; present on products flagged elsewhere.

PortalCommerceListPage ​

One page of a cursor-paged product list.

NameTypeRequiredDescription
productsT[]YesThe products of this page.
pageSizenumberYesThe page size used.
nextCursorstring | nullYesPass as the cursor to get the next page.
hasMorebooleanYesTrue 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:

NameTypeRequiredDescription
price_centsnumberYesPrice in cents (0 when no item was found).
tax_centsnumberYesTax in cents.
dynamicobjectYesThe allowed amount range for a DYNAMIC item, else null.
dynamic.minnumberYes—
dynamic.maxnumberYesThe largest length allowed.
purchasablebooleanYesFalse when the price could not be resolved.
price_adjustmentsArray<Record<string, unknown>>NoPrice adjustments applied (sales, markets).

PortalCommerceProductQuery ​

Filters and paging for catalogue reads (shop.catalog.products(), productsPage(), Portal.commerce.getProducts()).

NameTypeRequiredDescription
categorystringNoOnly products of this category (slug or reference).
pagenumberNo1-based page number.
limitnumberNoPage size.
storestringNoThe store reference, when the call is not made through a store instance.
searchstringNoFree-text filter on the product name. For ranked search use shop.search.search().
sortstringNoSort order key, for example 'price_asc'.
include_imagesbooleanNoInclude image addresses with each product.

PortalCommercePurchaseView ​

What an invoice paid for, as the store sees it (shop.account.purchase()).

NameTypeRequiredDescription
statusstringYesPayment status.
paidbooleanYesTrue when it is paid.
amount_centsnumberYesAmount in cents.
currencystringYesISO currency code.
charge_idstring | nullYesThe provider's charge id.
refunded_centsnumberYesCents refunded.
linesobject[]YesThe purchased lines.
lines[].item_refstringYesThe Direct Payments item reference.
lines[].namestringYesThe name.
lines[].quantitynumberYesHow many.
lines[].unit_centsnumberYes—
lines[].tax_centsnumberYes—

PortalCommerceRecommendationsResult ​

One recommendation set.

NameTypeRequiredDescription
kindstringYesThe kind asked for.
hitsArray<Record<string, unknown>>YesThe recommended products.

PortalCommerceRentalAvailability ​

The answer to rentalAvailability(): the rules and the per-day free units of a rental variant.

NameTypeRequiredDescription
variant_refstringYesThe variant.
min_daysnumberYesShortest rental allowed, in days.
max_daysnumber | nullYesLongest rental allowed, or null for no limit.
max_days_aheadnumberYesHow far ahead a rental can start, in days.
rental_item_reference_numstringYesThe per-day price item.
deposit_item_reference_numstring | nullYesThe deposit item, or null.
day_price_centsnumber | nullYesPrice per day in cents, or null when not priced.
deposit_centsnumber | nullYesDeposit in cents, or null.
daysPortalCommerceRentalDay[]YesThe requested days.

PortalCommerceRentalDates ​

Custom-attribute keys a rental add-to-cart sends (YYYY-MM-DD).

NameTypeRequiredDescription
rental_starts_onstringYesFirst rental day.
rental_ends_onstringYesLast rental day (inclusive).

PortalCommerceRentalDay ​

One day of a rental variant's availability calendar.

NameTypeRequiredDescription
datestringYesThe day, YYYY-MM-DD.
availablenumber | nullYesUnits 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.

NameTypeRequiredDescription
starts_onstringYesFirst rental day, YYYY-MM-DD.
ends_onstringYesLast rental day, YYYY-MM-DD (inclusive).
daysnumberYesNumber of rental days.
rental_item_reference_numstringYesThe per-day price item.
rental_quantitynumberYesUnits x days, the quantity of the rental item on the invoice.
deposit_item_reference_numstring | nullYesThe deposit item, or null when there is no deposit.
deposit_unit_centsnumber | nullYesDeposit per unit in cents.
deposit_centsnumberYesTotal deposit of the line in cents.

PortalCommerceSavedItem ​

A cart line the shopper put aside ("save for later").

NameTypeRequiredDescription
idnumberYesThe saved item's id; pass it to moveSavedToCart() / removeSaved().
variant_refstringNoThe variant saved.
product_refstringNoThe product it belongs to.
product_slugstring | nullNoThe product's URL slug.
product_namestringYesThe product's name.
variant_titlestringYesThe variant's title.
quantitynumberYesUnits saved.
unit_price_centsnumberYesPrice of one unit in cents.
custom_attributesRecord<string, unknown>NoThe buyer's choices stored on the item.
available_quantitynumber | nullNoUnits in stock, or null when unlimited.
availabilitystringNoThe stock state.
purchasablebooleanNoFalse when the item can no longer be bought.

PortalCommerceSearchOptions ​

Options of shop.search.search().

NameTypeRequiredDescription
sortstringNoSort order key.
cursorstringNoThe cursor of the previous result, to get the next page.
limitnumberNoPage size.
filtersRecord<string, unknown>NoFacet filters, for example { color: ['red'] }.

PortalCommerceSearchResult ​

The answer to a search.

NameTypeRequiredDescription
hitsArray<Record<string, unknown>>YesThe matching products.
facetsRecord<string, unknown>NoCounts per filter value, to draw the filter sidebar.
totalnumberYesTotal matches.
cursorstring | nullNoPass to the next call for the next page; null/absent at the end.
corrected_querystring | nullNoThe spelling the engine searched for instead, when it corrected the query.

PortalCommerceSuggestResult ​

The answer to shop.search.suggest().

NameTypeRequiredDescription
suggestionsstring[]YesCompletions of the typed prefix.

PortalReturnRequest ​

The shopper-facing shape (no admin_note/decided_by, which are admin-only).

NameTypeRequiredDescription
reference_numstringYesThe request's reference.
order_reference_numstringYesThe order it is about.
store_reference_numstringYesThe store the order is from.
kind'return' | 'cancellation'YesA return of goods, or a cancellation of an order.
statusstringYesWhere the request stands. One of requested, approved, rejected, received, refunded, cancelled.
reasonstringYesThe shopper's reason.
notestring | nullNoThe shopper's note.
linesobject[]YesThe order lines and quantities involved.
lines[].order_line_idnumberYes—
lines[].quantitynumberYesHow many.
resolutionstring | nullNoHow it was resolved (refund, exchange...).
refund_centsnumber | nullNoCents refunded.
decided_atstring | nullNoISO time the store decided.
created_atstring | nullNoISO creation time.