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 |
Сторінка
Section titled “Сторінка”init({ shopId })
Section titled “init({ shopId })”Задає shop id, коли тег скрипта не може нести data-shop-id. Кидає Error на порожньому shopId. Див. Підключення.
config()
Section titled “config()”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 невідомий.
openHowItWorks()
Section titled “openHowItWorks()”Відкриває вікно «Як працює підписка» з вашої кнопки. Кидає Error, якщо на сторінці немає shop id.
Кнопки підписки
Section titled “Кнопки підписки”Детально — у Вибір покупця.
getOrderItems(lines)
Section titled “getOrderItems(lines)”Додає до рядків кошика 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' }]select(externalId, selection)
Section titled “select(externalId, selection)”selection — { mode: 'one_time' } або { mode: 'subscription', interval_value, interval_unit }. Невалідний вибір кидає TypeError. Кожна кнопка цього товару одразу показує новий вибір.
subscribe(fn)
Section titled “subscribe(fn)”fn(all) викликається при кожній зміні вибору, зокрема з іншої вкладки. Повертає функцію відписки.
Checkout
Section titled “Checkout”open({ orderId, locale? })
Section titled “open({ orderId, locale? })”Відкриває оформлення для замовлення, створеного через Shop API. Резолвиться, коли вікно відкрито. Див. Оформлення замовлення.
| Відхиляється з | Коли |
|---|---|
Error('open(): orderId is required') |
немає orderId |
Error('Shop is not ready') |
магазин не налаштував оплату чи доставку |
помилка з status: 404 |
замовлення не знайдено; також надходить neocarts:order-missing |
помилка з status: 0 |
немає мережі |
Помилка з status має також message — текст мовою покупця.
close()
Section titled “close()”Закриває оформлення. Подію neocarts:close не надсилає.
on(name, fn)
Section titled “on(name, fn)”Підписка на подію віджета. 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
Section titled “events”Назви подій як константи: 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 }}