Skip to content

JavaScript API

Once the script has loaded, window.NeocartsSubscription is available. All methods are synchronous except open() and config(), which return a Promise.

Method Returns Description
Page
init({ shopId }) void set the shop id when the tag has no data-shop-id (SPA, module)
config() Promise<WidgetConfig> shop settings: discount, intervals, palette
openHowItWorks() void open the «How the subscription works» window
Subscribe buttons
getOrderItems(lines) OrderItem[] cart lines → items for creating the order
select(externalId, selection) void save the choice for a product
get(externalId) Selection | null the choice for a product
all() Record<string, Selection> all choices
remove(externalId | externalId[]) void forget the choice for products
clear() void forget all choices
subscribe(fn) () => void fn(all) on every change of the selection
Checkout
open({ orderId, locale? }) Promise<void> open checkout for the order
close() void close checkout
Events
on(name, fn) () => void subscribe to an event
events object event names: Ready, SelectionChange, Paid, OrderMissing, Close

Sets the shop id when the script tag cannot carry data-shop-id. Throws an Error on an empty shopId. See Embedding.

const { name, discountPercent, intervals, palette, ready } = await NeocartsSubscription.config();
Field Type Description
name string shop name
discountPercent number | null subscription discount; null or 0 — no discount
intervals SubscriptionIntervals allowed intervals: units, min, max, presets
palette Palette widget palette
ready boolean the shop has set up payment and delivery; if false, buttons are not shown and open() rejects

Rejects when the page has no shop id or the shop id is unknown.

Opens the «How the subscription works» window from your own button. Throws an Error when the page has no shop id.

Details in Shopper selection.

Adds mode and, for a subscription, interval_value / interval_unit to the cart lines. A product without a choice becomes one_time. The result is the items for POST /v1/shop/orders/create.

const items = NeocartsSubscription.getOrderItems([
{ external_id: 'food', title: 'Brit Care Adult Large Breed', variant: '12 kg',
image_url: 'https://shop.example.com/i/brit.jpg', product_url: 'https://shop.example.com/p/brit',
price: 249000, quantity: 1 },
]);
// → [{ …, mode: 'subscription', interval_value: 4, interval_unit: 'week' }]

selection is { mode: 'one_time' } or { mode: 'subscription', interval_value, interval_unit }. An invalid choice throws a TypeError. Every button of that product shows the new choice immediately.

fn(all) is called on every change of the selection, including from another tab. Returns an unsubscribe function.

Opens checkout for an order created through the Shop API. Resolves once the window is open. See Checkout flow.

Rejects with When
Error('open(): orderId is required') no orderId
Error('Shop is not ready') the shop has not set up payment or delivery
an error with status: 404 order not found; neocarts:order-missing is also sent
an error with status: 0 no network

An error with status also has message — a text in the shopper’s language.

Closes checkout. Does not send neocarts:close.

Subscribes to a widget event. name is a string or a member of events; fn receives the event data (detail). Returns an unsubscribe function.

const off = NeocartsSubscription.on(NeocartsSubscription.events.Paid, ({ number }) => {
cart.clear();
});
off(); // unsubscribe
name events Data passed to fn When
'neocarts:ready' Ready {} the script has loaded
'neocarts:selection-change' SelectionChange Record<string, Selection> — all choices, keyed by external_id the shopper selection changed
'neocarts:paid' Paid { number: string } — the order number payment confirmed
'neocarts:order-missing' OrderMissing { reason: 'not_found' | 'cancelled' } the order is unavailable
'neocarts:close' Close {} the shopper closed checkout

The same events are dispatched on document as CustomEvent, with the data in event.detail. When each fires and what to do — Events.

Event names as constants: events.Ready, events.SelectionChange, events.Paid, events.OrderMissing, events.Close.

type IntervalUnit = 'day' | 'week';
type Selection =
| { mode: 'one_time' }
| { mode: 'subscription'; interval_value: number; interval_unit: IntervalUnit };
type SubscriptionIntervals = {
units: IntervalUnit[];
min: number; // 1
max: number; // 365
presets: Array<{ interval_value: number; interval_unit: IntervalUnit }>;
};
type Palette = 'default' | 'blue' | 'green' | 'purple' | 'orange' | 'burgundy' | 'teal' | 'neutral';
type WidgetConfig = {
name: string;
discountPercent: number | null;
intervals: SubscriptionIntervals;
palette: Palette;
ready: boolean;
};
type CartLine = {
external_id: string;
title: string;
variant?: string | null;
image_url: string;
product_url: string;
price: number; // kopecks
quantity: number; // 1–9
};
type OrderItem = CartLine &
({ mode: 'one_time' } | { mode: 'subscription'; interval_value: number; interval_unit: IntervalUnit });
type EventDetails = {
'neocarts:ready': Record<string, never>;
'neocarts:selection-change': Record<string, Selection>;
'neocarts:paid': { number: string };
'neocarts:order-missing': { reason: 'not_found' | 'cancelled' };
'neocarts:close': Record<string, never>;
};
interface NeocartsSubscription {
init(options: { shopId: string }): void;
config(): Promise<WidgetConfig>;
openHowItWorks(): void;
getOrderItems<L extends { external_id: string }>(lines: L[]): Array<L & OrderItem>;
select(externalId: string, selection: Selection): void;
get(externalId: string): Selection | null;
all(): Record<string, Selection>;
remove(externalIds: string | string[]): void;
clear(): void;
subscribe(fn: (all: Record<string, Selection>) => void): () => void;
open(options: { orderId: string; locale?: string }): Promise<void>;
close(): void;
on<E extends keyof EventDetails>(name: E, fn: (detail: EventDetails[E]) => void): () => void;
events: {
Ready: 'neocarts:ready';
SelectionChange: 'neocarts:selection-change';
Paid: 'neocarts:paid';
OrderMissing: 'neocarts:order-missing';
Close: 'neocarts:close';
};
}
declare global {
interface Window { NeocartsSubscription?: NeocartsSubscription }
}