Перейти до вмісту

JavaScript API

Після завантаження скрипта доступний обʼєкт window.NeocartsSubscription. Усі методи синхронні, крім open() і config(), які повертають Promise.

Метод Повертає Опис
Сторінка
init({ shopId }) void задати shop id, якщо тег без data-shop-id (SPA, модуль)
config() Promise<WidgetConfig> налаштування магазину: знижка, інтервали, палітра
openHowItWorks() void відкрити вікно «Як працює підписка»
Кнопки підписки
getOrderItems(lines) OrderItem[] рядки кошика → items для створення замовлення
select(externalId, selection) void зберегти вибір для товару
get(externalId) Selection | null вибір для товару
all() Record<string, Selection> усі вибори
remove(externalId | externalId[]) void забути вибір для товарів
clear() void забути всі вибори
subscribe(fn) () => void fn(all) при кожній зміні вибору
Checkout
open({ orderId, locale? }) Promise<void> відкрити оформлення замовлення
close() void закрити оформлення
Події
on(name, fn) () => void підписатися на подію
events обʼєкт назви подій: Ready, SelectionChange, Paid, OrderMissing, Close

Задає shop id, коли тег скрипта не може нести data-shop-id. Кидає Error на порожньому shopId. Див. Підключення.

const { name, discountPercent, intervals, palette, ready } = await NeocartsSubscription.config();
Поле Тип Опис
name string назва магазину
discountPercent number | null знижка на підписку; null або 0 — без знижки
intervals SubscriptionIntervals дозволені інтервали: units, min, max, presets
palette Palette палітра віджета
ready boolean магазин налаштував оплату й доставку; якщо false, кнопки не показуються, а open() відхиляється

Відхиляється, якщо на сторінці немає shop id або shop id невідомий.

Відкриває вікно «Як працює підписка» з вашої кнопки. Кидає Error, якщо на сторінці немає shop id.

Детально — у Вибір покупця.

Додає до рядків кошика mode і, для підписки, interval_value / interval_unit. Товар без вибору стає one_time. Результат — items для POST /v1/shop/orders/create.

const items = NeocartsSubscription.getOrderItems([
{ external_id: 'food', title: 'Brit Care Adult Large Breed', variant: '12 кг',
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 — { mode: 'one_time' } або { mode: 'subscription', interval_value, interval_unit }. Невалідний вибір кидає TypeError. Кожна кнопка цього товару одразу показує новий вибір.

fn(all) викликається при кожній зміні вибору, зокрема з іншої вкладки. Повертає функцію відписки.

Відкриває оформлення для замовлення, створеного через Shop API. Резолвиться, коли вікно відкрито. Див. Оформлення замовлення.

Відхиляється з Коли
Error('open(): orderId is required') немає orderId
Error('Shop is not ready') магазин не налаштував оплату чи доставку
помилка з status: 404 замовлення не знайдено; також надходить neocarts:order-missing
помилка з status: 0 немає мережі

Помилка з status має також message — текст мовою покупця.

Закриває оформлення. Подію neocarts:close не надсилає.

Підписка на подію віджета. name — рядок або член events; fn отримує дані події (detail). Повертає функцію відписки.

const off = NeocartsSubscription.on(NeocartsSubscription.events.Paid, ({ number }) => {
cart.clear();
});
off(); // відписатися
name events Дані для fn Коли
'neocarts:ready' Ready {} скрипт завантажено
'neocarts:selection-change' SelectionChange Record<string, Selection> — усі вибори, ключ — external_id вибір покупця змінився
'neocarts:paid' Paid { number: string } — номер замовлення оплату підтверджено
'neocarts:order-missing' OrderMissing { reason: 'not_found' | 'cancelled' } замовлення недоступне
'neocarts:close' Close {} покупець закрив checkout

Ті самі події надходять на document як CustomEvent, дані — в event.detail. Коли й що робити з кожною — Події.

Назви подій як константи: 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; // копійки
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 }
}