JavaScript API

Headless API for programmatic interaction with MiniShop3 without DOM binding.

Architecture

MiniShop3 uses a two-layer architecture:

API Core (Headless)

Standalone core without DOM binding:

ApiClient.js — HTTP client for server requests
TokenManager.js — authorization token management
CartAPI.js — cart methods
OrderAPI.js — order methods
CustomerAPI.js — customer methods
hooks.js — hook system for extension

UI Layer (SSR)

DOM bindings for server-rendered markup:

CartUI.js — cart form handlers, rendering
OrderUI.js — order form handlers
CustomerUI.js — customer form handlers
ProductCardUI.js — product card state toggles

Loading

Full (default)

MiniShop3 plugin loads all scripts automatically. Controlled via system setting ms3_frontend_assets.

Minimal (Headless only)

For SPA apps (Vue, React, Svelte) load only the core:

html

<script src="/assets/components/minishop3/js/web/modules/hooks.js"></script>
<script src="/assets/components/minishop3/js/web/core/TokenManager.js"></script>
<script src="/assets/components/minishop3/js/web/core/ApiClient.js"></script>
<script src="/assets/components/minishop3/js/web/core/CartAPI.js"></script>
<script src="/assets/components/minishop3/js/web/core/OrderAPI.js"></script>
<script src="/assets/components/minishop3/js/web/core/CustomerAPI.js"></script>

Manual initialization

javascript

// Config
const config = {
  actionUrl: '/assets/components/minishop3/api.php',
  tokenName: 'ms3_token'
}

// Core init
const tokenManager = new TokenManager(config)
const apiClient = new ApiClient({ baseUrl: config.actionUrl, tokenManager })
tokenManager.setApiClient(apiClient)

// Getting the token
await tokenManager.ensureToken()

// API modules
const cart = new CartAPI(apiClient)
const order = new OrderAPI(apiClient)
const customer = new CustomerAPI(apiClient)

// Ready to use
const response = await ms3.cartAPI.add(123, 2, { color: 'red' })

Global objects

With standard loading the following are available:

Object	Description
`window.ms3`	Main object with all modules
`window.ms3Hooks`	Hook system
`window.ms3Message`	Notifications (if UI loaded)
`window.ms3Config`	Server config

ms3Config can be switched off by a setting

With ms3_register_global_config = false the object is not printed on the page. But the cart snippet registration is printed regardless and reaches for it without a check, so the console gets ReferenceError: ms3Config is not defined, and re-rendering of the cart and the totals widget stops working.

The setting is on by default. Turn it off only if you print the config yourself.

javascript

// Using the global object
await ms3.cartAPI.add(123, 1)
await ms3.orderAPI.submit()
await ms3.customerAPI.updateProfile({ email: 'new@example.com' })

CartAPI

API for working with the cart.

Methods

get()

Get cart contents.

javascript

const response = await ms3.cartAPI.get()

// response:
{
  success: true,
  message: "ms3_cart_get_success",
  data: {
    cart: {
      // Object where key is product_key
      "ms43ce202fd27c84c28230cc771328e37f": {
        id: 10,
        product_id: 152248,
        order_id: 7,
        product_key: "ms43ce202fd27c84c28230cc771328e37f",
        name: "Product name",
        count: 2,
        price: 148343,
        weight: 2.508,
        cost: 296686,
        options: [],
        properties: {
          old_price: 0,
          discount_price: 0,
          discount_cost: 0
        }
      }
    },
    status: {
      total_count: 9,
      total_cost: 1094850,
      total_weight: 35.62,
      total_discount: 19241,
      total_positions: 3
    }
  }
}

add(id, count, options, render)

Add product to cart.

Parameter	Type	Description
`id`	number	Product ID (required)
`count`	number	Quantity (default 1)
`options`	object	Product options (color, size, etc.)
`render`	array	Tokens for SSR (see below)

javascript

// Simple add
await ms3.cartAPI.add(123)

// With quantity
await ms3.cartAPI.add(123, 3)

// With options
await ms3.cartAPI.add(123, 1, { color: 'red', size: 'L' })

SSR (Server-Side Rendering)

The render parameter lets you get ready HTML from the server. Tokens must be registered on the server via TokenService. If tokens are set, HTML is returned in response.data.render. This is an advanced optimization — usually not needed.

Response format:

javascript

{
  success: true,
  message: "Product added to cart",
  data: {
    cart: {...},           // Cart lines, keyed by product_key
    status: {...},         // Totals
    render: {              // HTML (if requested)
      "ms3_a1b2c3...": "<div>...</div>"   // the key is the snippet call token
    }
  }
}

change(productKey, count, render)

Change product quantity.

Parameter	Type	Description
`productKey`	string	Unique product key in cart
`count`	number	New quantity
`render`	array	Tokens for rendering

javascript

await ms3.cartAPI.change('ms5d41d8cd98f00b204e9800998ecf8427e', 5)

product_key

Each product in the cart has a unique product_key. Same product with different options — different keys.

remove(productKey, render)

Remove product from cart.

javascript

await ms3.cartAPI.remove('ms5d41d8cd98f00b204e9800998ecf8427e')

clean(render)

Clear cart.

javascript

await ms3.cartAPI.clean()

An API call only

cartAPI.clean() is a headless method: it only sends the request to the server. The mini-cart, counters and product cards do not refresh by themselves. For a full UI update use ms3.cartUI.handleClean() — it calls the API, renders the HTML and dispatches ms3:cart:updated. More in Frontend JavaScript.

OrderAPI

API for working with the order.

Methods

get()

Get current order (session data).

javascript

const response = await ms3.orderAPI.get()

// response.data.order (fragment):
{
  delivery_id: 1,
  payment_id: 2,
  order_comment: "Call before delivery",
  address_first_name: "John",
  address_last_name: "Doe",
  address_email: "ivan@example.com",
  address_phone: "+79991234567",
  address_comment: ""
}

add(key, value)

Save order field.

javascript

await ms3.orderAPI.add('first_name', 'John')
await ms3.orderAPI.add('email', 'ivan@example.com')
await ms3.orderAPI.add('phone', '+79991234567')
await ms3.orderAPI.add('delivery_id', 1)
await ms3.orderAPI.add('payment_id', 2)
await ms3.orderAPI.add('order_comment', 'Call before delivery')
// address comment: await ms3.orderAPI.add('comment', '…')

Auto-save

Each add() call saves the value on the server. Data is not lost on page reload.

remove(key)

Remove order field.

javascript

await ms3.orderAPI.remove('order_comment')

clean()

Clear all order data.

javascript

await ms3.orderAPI.clean()

submit()

Checkout.

javascript

const response = await ms3.orderAPI.submit()

if (response.success) {
  // response.data:
  {
    order_id: 42,
    redirect: "/shop/order-success?msorder=42"
  }

  window.location.href = response.data.redirect
} else {
  // response:
  {
    success: false,
    message: "Fill required fields",
    data: {
      errors: ["first_name", "email", "phone"]
    }
  }
}

getCost()

Get order cost calculation.

javascript

const response = await ms3.orderAPI.getCost()

// response:
{
  success: true,
  message: "Cost calculated",
  data: {
    cost: 0,
    cart_cost: 0,
    delivery_cost: 0,
    payment_cost: 0,
    total_count: 0,
    total_cost: 0,
    total_weight: 0,
    total_discount: 0,
    total_positions: 0
  }
}

CustomerAPI

API for working with authenticated customer data.

Authorization required

Most CustomerAPI methods require authentication. The exceptions are login, registration and password reset: those exist precisely for someone who has not signed in yet. Guest order data is stored through OrderAPI.add().

Methods

updateProfile(data)

Update authenticated user profile.

javascript

await ms3.customerAPI.updateProfile({
  first_name: 'John',
  last_name: 'Doe',
  email: 'ivan@example.com',
  phone: '+79991234567'
})

createAddress(data)

Create new address.

javascript

await ms3.customerAPI.createAddress({
  name: 'Home',
  city: 'Moscow',
  street: 'Main St',
  building: '1',
  room: '10',
  index: '123456'
})

updateAddress(id, data)

Update existing address.

javascript

await ms3.customerAPI.updateAddress(5, {
  city: 'Saint Petersburg',
  street: 'Nevsky Prospect'
})

deleteAddress(id)

Remove address.

javascript

await ms3.customerAPI.deleteAddress(5)

Hook system

Hooks let you extend behavior without changing source code.

Registering a hook

javascript

ms3Hooks.addHook('hookName', async (context) => {
  // context — operation data
  // context.cancel = true — cancel the operation
})

Available hooks

Cart

Hook	Context	Description
`beforeAddCart`	`{ id, count, options }`	Before adding product
`afterAddCart`	`{ id, count, options, response }`	After adding product
`beforeChangeCart`	`{ productKey, count }`	Before changing quantity
`afterChangeCart`	`{ productKey, count, response }`	After changing quantity
`beforeRemoveCart`	`{ productKey }`	Before removing product
`afterRemoveCart`	`{ productKey, response }`	After removing product
`beforeCleanCart`	`{}`	Before clearing cart
`afterCleanCart`	`{ response }`	After clearing cart
`beforeChangeOptionCart`	`{ productKey, options }`	Before changing a line option
`afterChangeOptionCart`	`{ productKey, options, response }`	After changing an option
`beforeQuantityChange`	`{ productKey, count, form }`	Before a quantity change via the «+» and «−» buttons
`afterQuantityChange`	`{ productKey, count, response }`	After a quantity change

Order

Hook	Context	Description
`beforeAddOrder`	`{ key, value }`	Before saving field
`afterAddOrder`	`{ key, value, response }`	After saving field
`beforeSubmitOrder`	`{}`	Before submit
`afterSubmitOrder`	`{ response }`	After submit
`beforeCleanOrder`	`{}`	Before clear
`afterCleanOrder`	`{ response }`	After clear
`afterUpdateOrderCosts`	`{ cost, cart_cost, delivery_cost }`	After the order cost is recalculated

Customer

Hook	Context	Description
`beforeAddCustomer`	`{ key, value }`	Before saving data
`afterAddCustomer`	`{ key, value, response }`	After saving data
`beforeUpdateProfile`	`{ data }`	Before updating profile
`afterUpdateProfile`	`{ data, response }`	After updating profile
`beforeCreateAddress`	`{ data }`	Before creating address
`afterCreateAddress`	`{ data, response }`	After creating address
`beforeUpdateAddress`	`{ addressId, data }`	Before editing an address
`afterUpdateAddress`	`{ addressId, data, response }`	After editing an address
`beforeDeleteAddress`	`{ addressId }`	Before deleting an address
`afterDeleteAddress`	`{ addressId, response }`	After deleting an address
`beforeSetDefaultAddress`	`{ addressId }`	Before picking the default address
`afterSetDefaultAddress`	`{ addressId, response }`	After picking the default address
`beforeChangeAddressCustomer`	`{ addressId }`	Before switching the address in the order form
`afterChangeAddressCustomer`	`{ addressId, response }`	After switching the address
`beforeCancelOrder`	`{ orderId }`	Before the customer cancels an order
`afterCancelOrder`	`{ orderId, response }`	After an order is cancelled
`beforeResendVerificationEmail`	`{ button }`	Before resending the verification email
`afterResendVerificationEmail`	`{ button, response }`	After the email is sent

Hook	Context	Description
`beforeLogin`	`{ email }`	Before login
`afterLogin`	`{ email, response }`	After login
`beforeRegister`	`{ email }`	Before registration
`afterRegister`	`{ email, response }`	After registration

Any form

Hook	Context	Description
`beforeFormSubmit`	`{ entity, method, formData }`	Before any MiniShop3 form is submitted
`afterFormSubmit`	`{ entity, method, formData }`	After submission

This pair fires for every form — cart, order and customer — and receives the whole formData. Subscribe here when you need the entered values: the specialized hooks such as beforeSubmitOrder do not get the form data.

Hook examples

Validation before add:

javascript

ms3Hooks.addHook('beforeAddCart', async (ctx) => {
  if (!ctx.options.size) {
    alert('Select size!')
    ctx.cancel = true
  }
})

Analytics:

javascript

ms3Hooks.addHook('afterAddCart', async (ctx) => {
  if (!ctx.response.success) return

  gtag('event', 'add_to_cart', {
    currency: 'RUB',
    value: ctx.response.data.status.total_cost,
    items: [{ item_id: ctx.id, quantity: ctx.count }]
  })
})

ms3Hooks.addHook('afterSubmitOrder', async (ctx) => {
  if (!ctx.response.success) return

  gtag('event', 'purchase', {
    transaction_id: ctx.response.data.order_id,
    value: ctx.response.data.total_cost
  })
})

Clear confirmation:

javascript

ms3Hooks.addHook('beforeCleanCart', async (ctx) => {
  if (!confirm('Clear cart?')) {
    ctx.cancel = true
  }
})

DOM events

Event list

Event	Description	detail
`ms3:ready`	ms3 initialized	—
`ms3:cart:updated`	Cart updated	`{ cart, items, status }`, plus `render` on re-render. Sometimes arrives empty — see below

Subscribing

javascript

document.addEventListener('ms3:ready', () => {
  console.log('MiniShop3 ready')
})

document.addEventListener('ms3:cart:updated', (e) => {
  const { cart, items, status } = e.detail ?? {}
  if (!status) {
    return
  }

  // Update header counter
  document.querySelector('.cart-count').textContent = status.total_count
  document.querySelector('.cart-total').textContent = status.total_cost
})

The event also arrives without data

Clearing the order form dispatches it empty — detail will be null. The clearing form ships in the default chunk ms3_order.tpl, so the path is live: a handler that reads the fields straight away throws a TypeError (#802).

Check detail before touching the fields — every example below does.

Usage in SPA

Vue 3

javascript

// composables/useCart.js
import { ref, onMounted } from 'vue'

export function useCart() {
  const cart = ref([])
  const status = ref({ total_count: 0, total_cost: 0 })
  const loading = ref(false)

  async function loadCart() {
    loading.value = true
    const response = await ms3.cartAPI.get()
    if (response.success) {
      cart.value = response.data.cart
      status.value = response.data.status
    }
    loading.value = false
  }

  async function addToCart(id, count = 1, options = {}) {
    loading.value = true
    const response = await ms3.cartAPI.add(id, count, options)
    if (response.success) {
      cart.value = response.data.cart
      status.value = response.data.status
    }
    loading.value = false
    return response
  }

  async function removeFromCart(productKey) {
    const response = await ms3.cartAPI.remove(productKey)
    if (response.success) {
      cart.value = response.data.cart
      status.value = response.data.status
    }
    return response
  }

  async function changeQuantity(productKey, count) {
    const response = await ms3.cartAPI.change(productKey, count)
    if (response.success) {
      cart.value = response.data.cart
      status.value = response.data.status
    }
    return response
  }

  async function clearCart() {
    const response = await ms3.cartAPI.clean()
    if (response.success) {
      cart.value = []
      status.value = { total_count: 0, total_cost: 0 }
    }
    return response
  }

  onMounted(() => {
    loadCart()

    // Subscribe to external updates
    document.addEventListener('ms3:cart:updated', (e) => {
      if (!e.detail) {
        return
      }
      cart.value = e.detail.cart
      status.value = e.detail.status
    })
  })

  return {
    cart,
    status,
    loading,
    addToCart,
    removeFromCart,
    changeQuantity,
    clearCart,
    loadCart
  }
}

Usage in component:

vue

<script setup>
import { useCart } from '@/composables/useCart'

const { cart, status, loading, addToCart, removeFromCart } = useCart()
</script>

<template>
  <div class="cart">
    <div v-if="loading">Loading...</div>

    <div v-for="item in cart" :key="item.product_key" class="cart-item">
      <span>{{ item.pagetitle }}</span>
      <span>{{ item.count }} x {{ item.price }}</span>
      <button @click="removeFromCart(item.product_key)">Remove</button>
    </div>

    <div class="cart-total">
      Total: {{ status.total_cost }}
    </div>
  </div>
</template>

React

javascript

// hooks/useCart.js
import { useState, useEffect, useCallback } from 'react'

export function useCart() {
  const [cart, setCart] = useState([])
  const [status, setStatus] = useState({ total_count: 0, total_cost: 0 })
  const [loading, setLoading] = useState(false)

  const loadCart = useCallback(async () => {
    setLoading(true)
    const response = await window.ms3.cartAPI.get()
    if (response.success) {
      setCart(response.data.cart)
      setStatus(response.data.status)
    }
    setLoading(false)
  }, [])

  const addToCart = useCallback(async (id, count = 1, options = {}) => {
    setLoading(true)
    const response = await window.ms3.cartAPI.add(id, count, options)
    if (response.success) {
      setCart(response.data.cart)
      setStatus(response.data.status)
    }
    setLoading(false)
    return response
  }, [])

  const removeFromCart = useCallback(async (productKey) => {
    const response = await window.ms3.cartAPI.remove(productKey)
    if (response.success) {
      setCart(response.data.cart)
      setStatus(response.data.status)
    }
    return response
  }, [])

  useEffect(() => {
    loadCart()

    const handleCartUpdate = (e) => {
      if (!e.detail) {
        return
      }
      setCart(e.detail.cart)
      setStatus(e.detail.status)
    }

    document.addEventListener('ms3:cart:updated', handleCartUpdate)
    return () => document.removeEventListener('ms3:cart:updated', handleCartUpdate)
  }, [loadCart])

  return { cart, status, loading, addToCart, removeFromCart, loadCart }
}

Vanilla JavaScript

javascript

class CartManager {
  constructor() {
    this.cart = []
    this.status = { total_count: 0, total_cost: 0 }
    this.listeners = []
  }

  async init() {
    await this.load()

    document.addEventListener('ms3:cart:updated', (e) => {
      if (!e.detail) {
        return
      }
      this.cart = e.detail.cart
      this.status = e.detail.status
      this.notify()
    })
  }

  async load() {
    const response = await ms3.cartAPI.get()
    if (response.success) {
      this.cart = response.data.cart
      this.status = response.data.status
      this.notify()
    }
  }

  async add(id, count = 1, options = {}) {
    const response = await ms3.cartAPI.add(id, count, options)
    if (response.success) {
      this.cart = response.data.cart
      this.status = response.data.status
      this.notify()
    }
    return response
  }

  subscribe(callback) {
    this.listeners.push(callback)
    return () => {
      this.listeners = this.listeners.filter(l => l !== callback)
    }
  }

  notify() {
    this.listeners.forEach(cb => cb(this.cart, this.status))
  }
}

// Usage
const cartManager = new CartManager()
await cartManager.init()

cartManager.subscribe((cart, status) => {
  document.querySelector('.cart-count').textContent = status.total_count
})

document.querySelector('.add-to-cart').addEventListener('click', () => {
  cartManager.add(123, 1, { size: 'L' })
})

Response format

All methods return a Promise with an object:

javascript

{
  success: true,           // Operation success
  message: "Text",         // Message (optional)
  data: {                  // Data (when success: true)
    cart: {...},
    status: {...},
    render: {...}
  }
}

On error:

javascript

{
  success: false,
  message: "Error description",
  data: {
    errors: ["field1", "field2"]  // Error fields
  }
}

Tokens and authorization

MiniShop3 uses tokens to identify the cart session.

How it works

On the first request the client gets a token (GET /api/v1/customer/token/get, or it is minted automatically on the first cart call)
Since 1.6 the main browser approach is httpOnly cookie ms3_token, not localStorage
Same-site requests use credentials: 'include'; headless can send Authorization: Bearer
Rotation on login / token/refresh

Details: Web API authorization, Frontend JavaScript.

Manual control

javascript

// Get a token from the server if there is none yet
await ms3.tokenManager.ensureToken()

// Force a new one
await ms3.tokenManager.fetchNewToken()

Both methods call /api/v1/customer/token/get, and the server sets the cookie in its response.

The token cannot be read from the browser

getToken() and getTokenData() always return null, and setToken() does nothing. That is not a bug: since 1.6 the token lives in an httpOnly cookie, and JavaScript has no access to it — that is the whole point of such a cookie.

removeToken() does not remove the current token either: it only cleans up leftovers in localStorage from earlier versions. The cart session cannot be reset from the browser; the server does that.

Frontend JavaScript — full documentation including UI
REST API — server endpoints
Events — component PHP events

JavaScript API ​

Architecture ​

API Core (Headless) ​

UI Layer (SSR) ​

Loading ​

Full (default) ​

Minimal (Headless only) ​

Manual initialization ​

Global objects ​

CartAPI ​

Methods ​

get() ​

add(id, count, options, render) ​

change(productKey, count, render) ​

remove(productKey, render) ​

clean(render) ​

OrderAPI ​

Methods ​

get() ​

add(key, value) ​

remove(key) ​

clean() ​

submit() ​

getCost() ​

CustomerAPI ​

Methods ​

updateProfile(data) ​

createAddress(data) ​

updateAddress(id, data) ​

deleteAddress(id) ​

Hook system ​

Registering a hook ​

Available hooks ​

Cart ​

Order ​

Customer ​

Login and registration ​

Any form ​

Hook examples ​

DOM events ​

Event list ​

Subscribing ​

Usage in SPA ​

Vue 3 ​

React ​

Vanilla JavaScript ​

Response format ​

Tokens and authorization ​

How it works ​

Manual control ​

Related pages ​

JavaScript API

Architecture

API Core (Headless)

UI Layer (SSR)

Loading

Full (default)

Minimal (Headless only)

Manual initialization

Global objects

CartAPI

Methods

get()

add(id, count, options, render)

change(productKey, count, render)

remove(productKey, render)

clean(render)

OrderAPI

Methods

get()

add(key, value)

remove(key)

clean()

submit()

getCost()

CustomerAPI

Methods

updateProfile(data)

createAddress(data)

updateAddress(id, data)

deleteAddress(id)

Hook system

Registering a hook

Available hooks

Cart

Order

Customer

Login and registration

Any form

Hook examples

DOM events

Event list

Subscribing

Usage in SPA

Vue 3

React

Vanilla JavaScript

Response format

Tokens and authorization

How it works

Manual control

Related pages