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.
How it works
Section titled “How it works”- The shopper adds a subscription in the subscribe button (or your switch calls
select()). - The choice is kept in the shopper’s browser for each
external_id. It is shared by all pages and tabs. - On «Checkout» the cart calls
getOrderItems(lines)and gets lines withmodeand the interval. - Your server creates the order with these lines through
POST /v1/shop/orders/create. - After a successful payment the widget clears the selection.
Quantity and price stay in your cart — the widget does not store them.
From cart to order
Section titled “From cart to order”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.
Methods
Section titled “Methods”| 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.
Selection format
Section titled “Selection format”| 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 400Your own switch
Section titled “Your own switch”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 sourcenc.subscribe((all) => renderPickers(all));The full list of values is in Enums.