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 |
init({ shopId })
Section titled “init({ shopId })”Sets the shop id when the script tag cannot carry data-shop-id. Throws an Error on an empty shopId. See Embedding.
config()
Section titled “config()”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.
openHowItWorks()
Section titled “openHowItWorks()”Opens the «How the subscription works» window from your own button. Throws an Error when the page has no shop id.
Subscribe buttons
Section titled “Subscribe buttons”Details in Shopper selection.
getOrderItems(lines)
Section titled “getOrderItems(lines)”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' }]select(externalId, selection)
Section titled “select(externalId, selection)”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.
subscribe(fn)
Section titled “subscribe(fn)”fn(all) is called on every change of the selection, including from another tab. Returns an unsubscribe function.
Checkout
Section titled “Checkout”open({ orderId, locale? })
Section titled “open({ orderId, locale? })”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.
close()
Section titled “close()”Closes checkout. Does not send neocarts:close.
Events
Section titled “Events”on(name, fn)
Section titled “on(name, fn)”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(); // unsubscribename |
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.
events
Section titled “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 }}