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.
Example
Section titled “Example”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 });Details
Section titled “Details”neocarts:ready
Section titled “neocarts:ready”Fires once. If your code runs later, the event is gone — so check window.NeocartsSubscription first, as in the example.
neocarts:paid
Section titled “neocarts:paid”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.
neocarts:order-missing
Section titled “neocarts:order-missing”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 |
neocarts:close
Section titled “neocarts:close”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.