Skip to content

Shopper selection

The shopper selection is what the shopper chose for each product: a one-time purchase or a subscription at a given frequency. The subscribe buttons record it themselves, and your cart turns it into order lines with one getOrderItems() call.

  1. The shopper adds a subscription in the subscribe button (or your switch calls select()).
  2. The choice is kept in the shopper’s browser for each external_id. It is shared by all pages and tabs.
  3. On «Checkout» the cart calls getOrderItems(lines) and gets lines with mode and the interval.
  4. Your server creates the order with these lines through POST /v1/shop/orders/create.
  5. After a successful payment the widget clears the selection.

Quantity and price stay in your cart — the widget does not store them.

const lines = cart.map((l) => ({ external_id: l.sku, quantity: l.quantity }));
const items = NeocartsSubscription.getOrderItems(lines);
// [{ external_id: 'food', quantity: 1, mode: 'subscription', interval_value: 4, interval_unit: 'week' },
// { external_id: 'bowl', quantity: 2, mode: 'one_time' }]
const order = await fetch('/api/neocarts/order', { // your server
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ items }),
}).then((r) => r.json());
await NeocartsSubscription.open({ orderId: order.id });

getOrderItems() adds mode to every line, and interval_value and interval_unit for a subscription. A product without a choice becomes one_time. Other line fields are left as they are.

Only external_id, the quantity and the choice go from the browser to your server. The server takes the title, variant, image, link and price from its own database by external_id and builds the POST /v1/shop/orders/create lines from them. Do not trust a price that came from the browser.

Method Description
getOrderItems(lines) cart lines → items for creating the order
select(externalId, selection) save the choice for a product
get(externalId) the choice for a product or null
all() all choices, keyed by external_id
remove(id | ids[]) forget the choice for products
clear() forget everything
subscribe(fn) fn(all) on every change; returns an unsubscribe function

Signatures and types are in the JavaScript API.

Field Type Required Description
mode string yes one_time or subscription
interval_value integer for subscription 1–365 (the shop’s limits). Example: 4
interval_unit string for subscription day or week
NeocartsSubscription.select('food', { mode: 'subscription', interval_value: 2, interval_unit: 'week' });
NeocartsSubscription.select('food', { mode: 'one_time' });

An invalid choice (empty externalId, unknown mode, an interval outside the shop’s limits) throws a TypeError:

[Neocarts] select(): interval_value must be an integer 1–365, got 400

The subscribe button fully covers frequency selection. If you need your own switch in the cart, build it from config().intervals and write to the same store with select(). Subscribe buttons show the new choice immediately.

const nc = window.NeocartsSubscription;
const { intervals } = await nc.config();
// intervals.presets: [{ interval_value: 1, interval_unit: 'week' }, ...]
// intervals.min, intervals.max, intervals.units
chip.onclick = () => nc.select('food', { mode: 'subscription', ...intervals.presets[1] });
oneTime.onclick = () => nc.select('food', { mode: 'one_time' });
// re-render switches from the single source
nc.subscribe((all) => renderPickers(all));

The full list of values is in Enums.