Skip to content

Events

The widget tells the page about key moments with events on document. Subscribe with NeocartsSubscription.on(name, fn) — the handler receives the event data and you get an unsubscribe function back. document.addEventListener works too (data in event.detail).

Event Payload When What to do
neocarts:ready {} the script has loaded initialise your code
neocarts:selection-change all choices: Record<external_id, Selection> the shopper changed a subscription in a button; your select() / remove() / clear(); a change in another tab update the cart and switches
neocarts:paid { number } payment confirmed empty the cart, forget order.id
neocarts:order-missing { reason: 'not_found' | 'cancelled' } the order is unavailable forget order.id, create a new one next time
neocarts:close {} the shopper closed checkout analytics, focus — if needed

Names are also available as NeocartsSubscription.events.Ready, .SelectionChange, .Paid, .OrderMissing, .Close.

const ready = () => {
const nc = window.NeocartsSubscription;
nc.on(nc.events.Paid, ({ number }) => {
cart.clear();
localStorage.removeItem('my-shop:order-id');
showNotice(`Paid: order № ${number}`);
});
nc.on(nc.events.OrderMissing, () => {
localStorage.removeItem('my-shop:order-id');
showError('The order is no longer available — please check out again.');
});
nc.on(nc.events.SelectionChange, (all) => renderCart(all));
};
if (window.NeocartsSubscription) ready();
else document.addEventListener('neocarts:ready', ready, { once: true });

Fires once. If your code runs later, the event is gone — so check window.NeocartsSubscription first, as in the example.

Fires once payment is confirmed — in the open checkout or when the shopper reopens an already paid order. By then the widget has already cleared the shopper selection. The server receives the order.paid webhook — rely on it, not on the browser event, to fulfil the order.

reason When
not_found wrong id, the order was deleted, or it was paid/cancelled more than 24 hours ago
cancelled the order was cancelled in the panel

Only when the shopper closes checkout (✕, Esc, the success screen). Calling close() does not send it. After payment neocarts:paid comes first, and neocarts:close when the shopper closes the success screen.