Послідовність подій
Кожна подія описана на своїй сторінці; тут — як вони складаються в ланцюжки. У всіх сценаріях 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 стосується лише продовжень.
2. Продовження
Section titled “2. Продовження”Neocarts у день next_charge_at відкриває замовлення на продовження і списує гроші з картки, збереженої для підписки.
Neocarts відкрив замовлення на продовження └─ order.created source: "subscription"
списання пройшло ├─ subscription.renewed previous_next_charge_at → next_charge_at на інтервал уперед └─ order.paid payment: {…}, confirmed_manually: falsesubscription.renewed несе order_id цього замовлення і previous_next_charge_at. Замовлення на продовження несе одну позицію — цю підписку.
3. Невдале продовження
Section titled “3. Невдале продовження”Списання відхилено або платіж висить понад 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 — на сторінках подій.
6. Минув paused_until
Section titled “6. Минув paused_until”Підписку поставили на паузу до дати. Коли дата настала, Neocarts сам повертає її в active.
paused_until настав └─ subscription.resumed previous_status: "paused", reason_key: nullТа сама подія, що й при ручному відновленні; paused_until у знімку після відновлення завжди null.
7. Дії покупця
Section titled “7. Дії покупця”Покупець може змінити підписку сам. Кожна дія — ті самі події, що й з панелі.
пропуск доставки 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 — перевірка картки, пропустити |