CMS Tool API schema
Public API version 1.4.51.
Shop Configuration
The shop settings of one shopping page as a single flat object: currency and tax, how products, prices, stock and buy buttons are displayed, checkout options, order numbering, notifications and how long customers may edit or cancel a submitted order.
Endpoint URL
https://api.cms-tool.net/api/shopconfig
/api/shopconfig
Read and update the shop configuration of each shopping page as one flat object.
GET
List the shop configuration of every shopping page, or retrieve one by appending its page ID to the path.
Query parameters
| Name | Type | Example | Notes |
|---|---|---|---|
page | int | 123 | Filter results by page. |
POST
Update the shop configuration of a shopping page from a JSON object. Send only the settings to change.
Request content type: application/json
Request body fields
| Name | Type | Example | Notes |
|---|---|---|---|
page | int | 123 | Set the page value. |
currency | text | NZD | Three letter ISO currency code that prices on the shopping page are charged in. |
taxRate | number | 19.95 | Sales tax (GST/VAT) rate as a percentage, from 0 to 100. |
taxNumber | text | GST 123-456-789 | The merchant's sales tax registration number, up to 30 characters. |
priceDisplayFormat | text | INCL | How prices and tax are displayed at checkout, for example AUTO, EXCL, INCL or INCLEXCL. |
priceEntryFormat | text | Incl | How prices are entered: Excl, Incl, Split or Mixed. |
orderNumberPrefix | text | WW | Text added in front of order and invoice numbers. |
nextInvoiceNumber | int | 123 | The number the next invoice will use. |
hideSavingsAndRrp | boolean | true | Hide savings and RRP prices and totals. Accepts true or 1. |
showVoucherBox | boolean | true | Show the promo code and voucher redemption box in the cart and checkout. Accepts true or 1. |
minLevelToBuy | int | 123 | Lowest member level that may see the buy button: 0 everyone, 100 logged in, 200 to 500 authorised levels, 999 no one. |
Any setting listed in the field dictionary may be posted, not only those shown here. The page field selects the shopping page and may be omitted when the website has only one. Unknown fields are ignored. An empty value clears a setting, and a flag set to false or 0 is turned off. If any value is not valid, nothing is saved and the error names each field.
Data definitions
| Field | Type | Description | Format | Example |
|---|---|---|---|---|
quantityControl | text | Buy quantity control: COMBO (combo with #.###), MINMAX (combo without #.###), TEXT (text box), PLUSMINUS, REMOVE (remove only) or NONE (no quantity option). | ||
redirectSingleProductCategory | bool | True to send a visitor straight to the product when a category holds only one product. | ||
hideProductCode | bool | t to hide the product code on product pages and lists. | ||
weeklyOutOfStockReport | bool | True to send the merchant a weekly out of stock report. | ||
checkoutFileUpload | text | Checkout file upload: SaveWithOrder (saved with the order) or TempByEmail (kept temporarily and emailed separately). Blank disables uploads. | ||
vipPricing | bool | True to give logged in opted-in or authorised members VIP prices (price group A). | ||
linkedProductSearch | text | How linked products are found: BiDirectional (links work both ways) or Children (child products only). | ||
hoverImageSlideshow | bool | True to reveal a slideshow of the additional images when the pointer rests on a product in a list. | ||
cancelCutoffBeforeDelivery | interval | How long before the target delivery date or booking start the customer may still cancel, eg 1 day, 1 week. 0 or blank disables cancelling before delivery. | ||
showPromoStamps | bool | True to show promotion stamps on products. | ||
categoryHeaderLayout | text | Category header layout: none, 320left, 320right, 160left, 160right (medium or small image left or right of the summary text), text (summary text only), imgtext (full image above the summary text) or textimg (full image below the summary text). | ||
listShowTags | bool | True to show linked categories as tags in product lists. | ||
showOrderMarketingSource | bool | True to show marketing source details when viewing orders. | ||
productShowSupplier | bool | True to show the supplier on the product page. | ||
listShowCode | text | Set to BelowDescription to show the product code below the description in product lists. Blank does not show it. | ||
listBuyButtonFormat | text | Buy button format in product lists: BUTTONONLY, QTYBUTTON (quantity and buy button), BUTTONWITHOPTIONS (options, quantity and buy button), ViewAndBuy (view details and buy buttons), VIEWBUTTON (view link) or the last option on the shop setup screen, which shows nothing. Blank uses the default. | ||
hideUnitFromShortPrice | bool | True to hide the unit of measure from the short price. | ||
id | int | Shopping page ID. The same as page. | ||
categoryListFormat | text | Layout of the category list: -1 (no category list), 1, 2, 2LARGE, 3, 3LARGE, 4, 18, 5, 6, GRID, 9, 10, 11, 12, 13 or 14 (column, thumbnail, grid and bullet point layouts chosen on the shop setup screen). Blank uses the same layout as products. | ||
categoryPricingMode | text | Category pricing mode: blank disabled, Price Discount or Cost Plus. | ||
showDocketWeights | bool | True to show item weights on shipping dockets. | ||
showCartSubTotal | bool | True to show a sub total in the cart. | ||
listShowWeight | bool | True to show the product weight in product lists. | ||
hideSavingsAndRrp | bool | True to hide savings and RRP prices and totals. | ||
productShowPublisher | bool | True to show the publisher or manufacturer on the product page. | ||
taxNumber | text | Merchant's sales tax registration number (eg GST#, VAT#, ABN#), up to 30 characters. | ||
editCutoffBeforeDelivery | interval | How long before the target delivery date or booking start the customer may still edit the order, eg 1 day, 1 week. 0 or blank disables editing before delivery. | ||
listPagination | text | How a customer moves through long product lists: PAGES (page number buttons) or SHOWMORE (a show more button). | ||
showArtistsInCategories | bool | True to show the artists for exhibitions in category lists. | ||
extraField1 | text | Label for extra product field 1 on this shopping page. Blank means the field is not used. | ||
nextInvoiceNumber | int | The number the next invoice will use. Increases by one each time an order is submitted through the shop API. | ||
orderNumberPrefix | text | Prefix added to order and invoice numbers. | ||
editWindowAfterPurchase | interval | How long after submitting an order the customer may edit it, eg 1 hour, 1 day, 7 days. 0 or blank disables editing after purchase. | ||
showCartVolume | bool | True to show the total volume of the cart. | ||
showSavings | bool | t to show the savings value after the price and RRP. | ||
extraField6 | text | Label for extra product field 6 on this shopping page. Blank means the field is not used. | ||
listTradeOptionLayout | text | Trade option display format in product lists (a product option layout code). Blank uses the default. | ||
extraField4 | text | Label for extra product field 4 on this shopping page. Blank means the field is not used. | ||
extraField5 | text | Label for extra product field 5 on this shopping page. Blank means the field is not used. | ||
extraField2 | text | Label for extra product field 2 on this shopping page. Blank means the field is not used. | ||
categoryFooterLayout | text | Category footer layout, using the same codes as categoryHeaderLayout. | ||
extraField3 | text | Label for extra product field 3 on this shopping page. Blank means the field is not used. | ||
minLevelToSeePrices | int | Lowest member level that may see prices: 0 everyone, 100 logged in, 200 authorised users, 300 level 2, 400 level 3, 500 level 4, 999 no one. | ||
productShowTags | bool | True to show linked categories as tags on the product page. | ||
buyButtonLabel | text | Text on the buy button in product lists, up to 20 characters. Used when there is no buyButtonImage. | ||
rememberSize | bool | True to remember the customer's last size choice. | ||
limitToCountry | text | Limits checkout to one country, given as the country name from the merchant's contact details. Blank means no limit. | ||
cascadeVariantPricing | bool | True to cascade variant pricing by default. | ||
minimumOrderValue | decimal | Smallest order value a customer may check out with. Blank means no minimum. | ||
productImagePreference | text | Which image the product page shows first: Main (main image only), Material, Colour (selected colour swatch) or Style (selected style swatch). Blank uses the default variant image or the main image. | ||
priceEntryFormat | text | How the merchant enters prices when editing products: Excl (tax excluded), Incl (tax included), Split (dual price entry) or Mixed (retail incl, trade excl). | ||
listStockDisplayFormat | text | How stock availability is shown in product lists. A stock display code, as for stockDisplayFormat. | ||
showSaveCartButton | bool | True to show a Continue and Save Cart button in the order summary. | ||
checkoutCampaignId | int | ID of the email campaign that customers are subscribed to at checkout. Blank means none. | ||
currency | text | Three letter ISO currency code that prices on this shopping page are entered and charged in, eg NZD. | ||
showPriceRange | bool | True to show a price range for products whose variants have different prices. | ||
askGiftMessage | bool | t to ask the customer for a gift message at checkout. | ||
rememberStyle | bool | True to remember the customer's last style or option choice. | ||
blockCrossPagePurchases | bool | True to prevent purchases between different shopping pages in one order. | ||
productTabsLocation | text | Where the product tabs go: DefaultLocation (full width, mid page) or UnderPriceTableBlock (under the details beside the photo). | ||
checkoutCampaignRule | text | Limits who is subscribed at checkout: NoPreviousOrders (only new customers with no previous orders). Blank means everyone. | ||
priceDisplayFormat | text | How prices and tax are displayed and calculated at checkout. AUTO (default), NONE, PRICE (tax excl, no wording), INCLQUIET (tax incl, no wording), EXCL (tax excl with wording), INCL (tax incl with wording), INCLEXCL (bold incl plus small excl), EXCLINCL (bold excl plus small incl), INCL_SHIPPING (shipping included, dual line), INCL_VIP (VIP pricing, dual line incl tax), INCL_TRADEEXCL (retail incl, trade excl). | ||
disableFastProductSearch | bool | True to turn off the fast search that goes straight to a product. | ||
suggestOnProduct | bool | t to suggest products on the product page (autosuggest plugin). | ||
checkoutAddressProcess | text | Checkout address process: METHODFIRST (delivery method first), SEARCHADDRESS (address search first), BOTH (delivery method and address search) or CHECKOUTBUTTON (checkout button only). | ||
rememberColour | bool | True to remember the customer's last colour choice. | ||
searchBoxStyle | text | Search box style on shopping pages: Default (keywords), Address (product availability by address), AdvancedLeft, AdvancedTop, Specifications, FiltersTopExpand or FiltersTopExpandAndSort. | ||
productRetailOptionLayout | text | Retail option display format on the product page (a product option layout code). DEFAULT uses the standard layout. | ||
showSortMenu | bool | t to show the product sorting dropdown on product lists. | ||
customerEditScope | text | What a customer may change on a submitted order: Notes (notes and contact details), NotesDeliveryDate (plus delivery date) or FullEdit (reopens the order). | ||
thumbnailClickAction | text | What clicking a product thumbnail does: ColourBoxSlideShow (popup slideshow) or ReplaceMainImage. Blank uses the default. | ||
stockDisplayFormat | text | How stock availability is shown on the product page. A stock display code, eg NONE, OOS, INSTOCKOUT, LOWSTOCKIFONE, INSTOCKONLY, QTY, QTYPOS, QTYBO, HIDE. | ||
optionsPrompt | text | Prompt text shown above the style/option choices on a product, up to 40 characters. | ||
showMerchantAddress | bool | t to show the merchant address footer on shopping pages. | ||
productBuyButtonLabel | text | Buy button label on the product page. | ||
priceRounding | decimal | Rounding step applied to tax inclusive prices: 0.00 (no rounding), 0.05, 0.10, 0.50 or 1.00. | ||
suggestAtCheckout | bool | t to suggest products at checkout (autosuggest plugin). | ||
sendTaxInvoices | bool | T to email order confirmations as tax invoices. Blank sends them as orders. | ||
listShowPricePer | bool | True to show the price per unit in product lists. | ||
suggestOutOfStock | bool | True to include out of stock products in product suggestions. | ||
lowStockLevel | decimal | Stock quantity at or below which a product counts as low stock. The setup screen starts at 5. | ||
listShowExtraFields | bool | True to show the product code and the extra product fields in product lists. | ||
showCategoryProductsOnProduct | bool | t to show other products in the same category, with images, on the product page. | ||
minLevelToEditOrders | int | Lowest member level that may edit or cancel their own orders: 100 logged in, 200 authorised users, 300 level 2, 400 level 3, 500 level 4. | ||
productShowWeight | bool | True to show the product weight on the product page. | ||
taxCalculatedBy | text | How tax is totalled on an order: Item (tax worked out on each item) or Line (tax worked out on each order line). | ||
showVoucherBox | bool | t to show the promo code / voucher redemption box in the cart and checkout. | ||
docketEmailOnOrder | text | Email address that receives the delivery docket when an order is submitted, before payment (up to 100 characters). | ||
deductVoucherTax | bool | True to deduct the GST on a voucher when it is redeemed. | ||
minLevelToBuy | int | Lowest member level that may see the buy button: 0 everyone, 100 logged in, 200 authorised users, 300 level 2, 400 level 3, 500 level 4, 999 no one. | ||
showProductSubtitle | bool | True to show the product subtitle on the product page. | ||
taxRate | decimal | Sales tax (GST/VAT) rate as a percentage, eg 15 for 15%. Product prices are stored excluding tax; this rate is added where prices are shown or charged tax inclusive. | ||
cartItemOrder | text | Item order in the cart: CHRONO (chronological), HISTORICAL, CODE or TITLE. | ||
listRetailOptionLayout | text | Retail option display format in product lists (a product option layout code). Blank means none. | ||
showContinueShoppingButton | bool | True to show a Continue Shopping button in the order summary. | ||
showCartWeight | bool | True to show the total weight of the cart. | ||
listShowAuthor | bool | True to show the author or artist in product lists. | ||
productTitleFormat | text | Product title format on the product page: TITLEONLY (name), CODETITLECAT (name (code) - category), TITLECAT (name - category), CODETITLE (code - name) or CATTITLE (category - name). | ||
listShowPublisher | bool | True to show the publisher in product lists. | ||
page | int | Shopping page ID that these settings belong to. | ||
marketplaceCategoryId | int | Marketplace category ID this shopping page is listed under (0 or blank when not categorised). | ||
docketItemOrder | text | Item order on delivery dockets: bi_id (default), p_title, p_code, p_location or p_suppliername. | ||
lastItemRule | text | Who gets the last item in stock when two customers want it: Add2Cart (the first to add it to the cart) or Checkout (the first to reach checkout). | ||
hideOutOfStockProducts | bool | True to leave out of stock products out of product lists. | ||
productTabsFormat | text | Product page tabs format: Tabs, Accordian (sections expand as required), AccordianSingular (one section open at a time) or Visible (no tabs). Accordian is the stored spelling. | ||
listShowColourSwatches | bool | True to show colour swatches in product lists. | ||
eventNotifications | text | When event booking notifications are sent for orders: OnOrderSubmit, OnOrderPaid or None. | ||
multiVariantForm | bool | True to show variants as one form where several options and quantities can be bought together. | ||
cancelWindowAfterPurchase | interval | How long after submitting an order the customer may cancel it, eg 1 hour, 1 day, 7 days. 0 or blank disables cancelling after purchase. | ||
requireFullName | bool | True to require the customer's full name at checkout. | ||
listShowQuantityBreaks | bool | True to show quantity price breaks in product lists. | ||
preferredDeliveryInput | text | How the customer gives a preferred delivery date or time: ShopHoursOnly (mandatory, within shop hours), FreeTextDate (free text with date picker), FreeText, Date, DateTime or Weekdays. Blank hides the question. | ||
buyButtonDestination | text | Where the buy button takes the customer: CART (shopping cart), CHECKOUT (checkout final step), LIST (top of product list), TOP (top of current page), POPUP (popup cart, full), POPUPCHANGES (popup cart, changes only), WIDGET (template specific), MESSAGE (small added to cart message that fades) or NUMBER (cart item count increase only). | ||
showPurchaseOrderField | bool | True to show a purchase order number field at checkout. | ||
buyButtonImage | text | Image used as the buy button in product lists. When blank, buyButtonLabel is used instead. | ||
unpaidOrderReminder | interval | How long after submitting an unpaid order the customer is reminded: an interval such as 1 day, 2 days, 1 week, 1 month. 0 disables the reminder. | ||
productTradeOptionLayout | text | Trade option display format on the product page (a product option layout code). Blank uses the default. | ||
docketEmailOnPayment | text | Email address that receives the delivery docket once an order is paid (up to 100 characters). | ||
showProductEnquiryForm | bool | True to include an enquiry form on the product page. | ||
showCategoryLinksOnProduct | bool | t to show a list of links to other products in the same category on the product page. | ||
productImageLayout | text | Product page image layout: slider, sliderthumbs, zoomleft, zoomright, inlinethumbs, squarethumbs, leftthumbs, 3colthumbs or thumbslider. | ||
checkoutAddressFormat | int | Checkout address format: 6 (basic customer contact and basic delivery address), 5 (basic customer contact and full delivery address with contacts), 3 (full customer and delivery addresses), 4 (full customer address plus billing email and full delivery address), 2 (full customer address block only), 1 (short customer address, not compatible with couriers or afterpay) or 0 (no postal addresses, digital delivery only). |
Usage instructions and examples
Each shopping page has one flat object with all of its shop settings. List them all with GET /api/shopconfig, or read one with GET /api/shopconfig/{page}. POST an object with the page and only the settings to change. An empty value clears a setting, a flag accepts true or 1, and if any value is not valid nothing is saved. Settings that are not set are returned as null, or false for a flag.
Sample object
{"id": 112137, "page": 112137, "currency": "NZD", "taxRate": 15, "taxNumber": "GST 123-456-789", "priceDisplayFormat": "INCL", "priceEntryFormat": "Incl", "orderNumberPrefix": "WW", "nextInvoiceNumber": 1042, "minLevelToBuy": 0, "showVoucherBox": true, "hideOutOfStockProducts": false, "lowStockLevel": 5, "unpaidOrderReminder": "2 days", "buyButtonLabel": null}Machine-readable documentation
This documentation is also available as JSON or Markdown at the same URL. Request JSON with Accept: application/json or Markdown with Accept: text/markdown.