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

Послідовність подій

Кожна подія описана на своїй сторінці; тут — як вони складаються в ланцюжки. У всіх сценаріях shop_id один і той самий, id кожної доставки — свій, created_at — момент події. Памʼятайте: доставки незалежні, і порядок надходження не гарантовано — повтор ранішої події може прийти після пізнішої. Ланцюжки нижче — порядок, у якому події стаються, не в якому вони обовʼязково прийдуть.

1. Перше замовлення з віджета

Section titled “1. Перше замовлення з віджета”

Покупець завершує checkout у віджеті — чернетка стає pending_payment. Потім оплата проходить, і в один момент замовлення стає paid, а з кожної позиції-підписки стартує підписка.

покупець завершив checkout
└─ order.created source: "widget", status: "pending_payment"
оплату зараховано
├─ subscription.created по одній на кожну позицію-підписку, order_id = замовлення
└─ order.paid payment: {…}, confirmed_manually: false,
subscription_ids вже заповнені

order.created — ще не продаж; повторна спроба checkout не повторює подію, незавершена чернетка не анонсується. order.paid і subscription.created стаються одночасно, тож прийти можуть у будь-якому порядку: якщо order.paid прийшов першим, subscription_ids у знімку вже каже, скільки підписок чекати. Якщо картку покупця відхилено на checkout, жодної події немає — payment.failed стосується лише продовжень.

Neocarts у день next_charge_at відкриває замовлення на продовження і списує гроші з картки, збереженої для підписки.

Neocarts відкрив замовлення на продовження
└─ order.created source: "subscription"
списання пройшло
├─ subscription.renewed previous_next_charge_at → next_charge_at на інтервал уперед
└─ order.paid payment: {…}, confirmed_manually: false

subscription.renewed несе order_id цього замовлення і previous_next_charge_at. Замовлення на продовження несе одну позицію — цю підписку.

Списання відхилено або платіж висить понад 24 години — Neocarts пробує знову через день, до пʼяти разів.

спроба 1 payment.failed attempt: 1, max_attempts: 5, next_attempt_at: +1 день
спроба 2 payment.failed attempt: 2, next_attempt_at: +1 день
спроба 3 payment.failed attempt: 3, next_attempt_at: +1 день
спроба 4 payment.failed attempt: 4, next_attempt_at: +1 день
спроба 5 payment.failed attempt: 5, next_attempt_at: null
subscription.paused previous_status: "active", reason_key: "charge_failed"
магазин відновив підписку в панелі
subscription.resumed previous_status: "paused", reason_key: null

Замовлення на продовження одне на період — те саме, що анонсував order.created зі сценарію 2; повторні спроби — нові платежі на тому ж замовленні, тож order_id у кожному payment.failed однаковий. payment.failed приходить на кожну спробу; після пʼятої разом з ним — subscription.paused з reason_key: "charge_failed". Далі лише subscription.resumed вручну повертає підписку в active. Якщо котрась зі спроб 2–5 пройшла — далі order.paid і subscription.renewed зі сценарію 2. Якщо між спробами сума змінилася (переоцінка товару чи інша кількість), старе замовлення закривається (order.cancelled) і відкривається нове (order.created) з новою серією спроб.

4. Немає збереженої картки

Section titled “4. Немає збереженої картки”

Neocarts підійшов до next_charge_at, а в підписки немає картки, з якої списати.

день списання, картки немає
└─ subscription.paused previous_status: "active", reason_key: "no_card"

Жодного order.created і жодного payment.failed — списання не починалося.

5. Дії в панелі магазину

Section titled “5. Дії в панелі магазину”

Кожна дія оператора — одна подія.

пауза підписки subscription.paused reason_key: "manual"
відновлення subscription.resumed previous_status: "paused" | "cancelled"
скасування subscription.cancelled cancellation_reason у знімку
зміна кількості subscription.updated changed: ["quantity"]
перенесення списання subscription.updated changed: ["interval_value","interval_unit","next_charge_at"]
зміна адреси доставки subscription.updated changed: ["delivery"]
переоцінка товару subscription.price_changed по одній на кожну підписку, previous_price
підтвердження оплати order.paid payment: null, confirmed_manually: true
закриття замовлення order.cancelled draft або pending_payment
повернення грошей payment.refunded refund_amount — це повернення

Масові дії над товаром (пауза чи скасування всіх підписок на товар) — це теж manual: по одній події на підписку. Переоцінка через PUT /v1/shop/products/{external_id}/price дає ті самі subscription.price_changed, що й панель; знімок уже з новою ціною. subscription.updated, subscription.cancelled, order.cancelled, payment.refunded — на сторінках подій.

Підписку поставили на паузу до дати. Коли дата настала, Neocarts сам повертає її в active.

paused_until настав
└─ subscription.resumed previous_status: "paused", reason_key: null

Та сама подія, що й при ручному відновленні; paused_until у знімку після відновлення завжди null.

Покупець може змінити підписку сам. Кожна дія — ті самі події, що й з панелі.

пропуск доставки subscription.updated changed: ["interval_value","interval_unit","next_charge_at"]
зміна частоти subscription.updated changed: ["interval_value","interval_unit","next_charge_at"]
пауза до дати subscription.paused reason_key: "customer", paused_until задано
відновлення з паузи subscription.resumed previous_status: "paused"
скасування subscription.cancelled cancellation_reason у знімку або null
інша адреса підписки subscription.updated changed: ["delivery"]
редагування адреси subscription.updated changed: ["delivery"], по одній на кожну підписку на адресі
заміна картки subscription.updated changed: ["card"]
payment.refunded order_id: null, повернення 1 ₴

Заміна картки не дає order.paid: платіж на 1 ₴ не має замовлення й одразу повертається. Якщо провайдер не зберіг токен, приходить лише payment.refunded. Призупинена підписка після заміни картки лишається на паузі, доки покупець її не відновить.

Що робити у своїй системі

Section titled “Що робити у своїй системі”
Подія Що робити
order.created зарезервувати товар або нічого — продажу ще немає
order.paid створити замовлення у своїй системі, відправити товар. Для source: "subscription" — це чергова відправка за підпискою
order.cancelled зняти резерв, якщо робили його на order.created
subscription.created завести підписку й покупця (знімок несе customer)
subscription.renewed оновити дату наступного списання; відправку робіть на order.paid
subscription.paused зупинити відправки; за reason_key вирішити, чи писати покупцеві (no_card, charge_failed)
subscription.resumed відновити відправки, взяти новий next_charge_at зі знімка
subscription.cancelled закрити підписку; cancellation_reason — для статистики
subscription.updated перезаписати поля з changed зі знімка
subscription.price_changed оновити ціну підписки у себе; наступне списання вже буде за новою
payment.failed повідомити покупця, якщо attempt ≥ 2; на next_attempt_at: null чекайте subscription.paused
payment.refunded провести повернення в обліку на refund_amount; order_id: null — перевірка картки, пропустити