Event flow
Every event has its own page; this one shows how they chain. In every scenario shop_id is the same, each delivery has its own id, and created_at is the moment of the event. Remember: deliveries are independent and arrival order is not guaranteed — a retry of an earlier event can land after a later one. The chains below are the order in which events happen, not the order in which they are sure to arrive.
1. First order from the widget
Section titled “1. First order from the widget”The shopper finishes the widget checkout — the draft becomes pending_payment. Then the payment settles, and in one moment the order becomes paid and a subscription starts from every subscription line.
shopper finished checkout └─ order.created source: "widget", status: "pending_payment"
payment settled ├─ subscription.created one per subscription line, order_id = the order └─ order.paid payment: {…}, confirmed_manually: false, subscription_ids already filledorder.created is not a sale yet; a retried checkout does not repeat it, and an unfinished draft is never announced. order.paid and subscription.created happen at the same moment, so they can arrive in either order: if order.paid comes first, subscription_ids in the snapshot already tells you how many subscriptions to expect. If the shopper’s card is refused at checkout there is no event at all — payment.failed is about renewals only.
2. Renewal
Section titled “2. Renewal”On the day of next_charge_at Neocarts opens a renewal order and charges the card saved for the subscription.
billing engine opened a renewal order └─ order.created source: "subscription"
charge settled ├─ subscription.renewed previous_next_charge_at → next_charge_at one interval out └─ order.paid payment: {…}, confirmed_manually: falsesubscription.renewed carries the order_id of that order and previous_next_charge_at. A renewal order has one line — this subscription.
3. Failed renewal
Section titled “3. Failed renewal”The charge was refused or the payment stayed pending for more than 24 hours — Neocarts tries again a day later, up to five times.
attempt 1 payment.failed attempt: 1, max_attempts: 5, next_attempt_at: +1 dayattempt 2 payment.failed attempt: 2, next_attempt_at: +1 dayattempt 3 payment.failed attempt: 3, next_attempt_at: +1 dayattempt 4 payment.failed attempt: 4, next_attempt_at: +1 dayattempt 5 payment.failed attempt: 5, next_attempt_at: null subscription.paused previous_status: "active", reason_key: "charge_failed"
the shop resumed the subscription in the panel subscription.resumed previous_status: "paused", reason_key: nullThere is one renewal order per billing period — the one order.created announced in scenario 2; retries are new payments on that same order, so order_id is the same in every payment.failed. payment.failed arrives for every attempt; after the fifth it is joined by subscription.paused with reason_key: "charge_failed". From there only a manual subscription.resumed brings the subscription back to active. If any of attempts 2–5 settles, order.paid and subscription.renewed from scenario 2 follow. If the amount changed between attempts (a product reprice or a different quantity), the old order is closed (order.cancelled) and a new one opened (order.created) with a fresh series of attempts.
4. No saved card
Section titled “4. No saved card”Neocarts reached next_charge_at and the subscription has no card to charge.
charge day, no card └─ subscription.paused previous_status: "active", reason_key: "no_card"No order.created and no payment.failed — the charge never started.
5. Shop panel actions
Section titled “5. Shop panel actions”Every operator action is one event.
pause a subscription subscription.paused reason_key: "manual"resume subscription.resumed previous_status: "paused" | "cancelled"cancel subscription.cancelled cancellation_reason in the snapshotchange quantity subscription.updated changed: ["quantity"]reschedule the charge subscription.updated changed: ["interval_value","interval_unit","next_charge_at"]change delivery address subscription.updated changed: ["delivery"]reprice a product subscription.price_changed one per subscription, previous_priceconfirm payment by hand order.paid payment: null, confirmed_manually: trueclose an order order.cancelled draft or pending_paymentrefund payment.refunded refund_amount is this refundBulk actions on a product (pause or cancel all its subscriptions) are manual too: one event per subscription. A reprice through PUT /v1/shop/products/{external_id}/price fires the same subscription.price_changed as the panel; the snapshot already has the new price. subscription.updated, subscription.cancelled, order.cancelled and payment.refunded are detailed on their pages.
6. paused_until passed
Section titled “6. paused_until passed”The subscription was paused until a date. When the date arrives, Neocarts brings it back to active on its own.
paused_until reached └─ subscription.resumed previous_status: "paused", reason_key: nullThe same event as a manual resume; paused_until in the snapshot is always null after a resume.
7. Shopper actions
Section titled “7. Shopper actions”The shopper can change the subscription themselves. Each action sends the same events as the panel.
skip a delivery subscription.updated changed: ["interval_value","interval_unit","next_charge_at"]change frequency subscription.updated changed: ["interval_value","interval_unit","next_charge_at"]pause until a date subscription.paused reason_key: "customer", paused_until setresume from a pause subscription.resumed previous_status: "paused"cancel subscription.cancelled cancellation_reason in the snapshot, or nullanother address subscription.updated changed: ["delivery"]edit a saved address subscription.updated changed: ["delivery"], one per subscription on the addressreplace the card subscription.updated changed: ["card"] payment.refunded order_id: null, the 1 ₴ refundA card replacement produces no order.paid: the 1 ₴ payment has no order and is refunded at once. If the provider saved no token, only payment.refunded arrives. A paused subscription stays paused after the card is replaced until the shopper resumes it.
What to do in your system
Section titled “What to do in your system”| Event | What to do |
|---|---|
order.created |
reserve stock, or nothing — there is no sale yet |
order.paid |
create the order in your system and ship. For source: "subscription" this is the next shipment of a subscription |
order.cancelled |
release the reservation if you made one on order.created |
subscription.created |
create the subscription and the customer (the snapshot carries customer) |
subscription.renewed |
update the next charge date; ship on order.paid |
subscription.paused |
stop shipments; use reason_key to decide whether to contact the customer (no_card, charge_failed) |
subscription.resumed |
resume shipments, take the new next_charge_at from the snapshot |
subscription.cancelled |
close the subscription; cancellation_reason is for your statistics |
subscription.updated |
overwrite the fields listed in changed from the snapshot |
subscription.price_changed |
update the subscription’s price on your side; the next charge already uses the new one |
payment.failed |
notify the customer once attempt ≥ 2; on next_attempt_at: null expect subscription.paused |
payment.refunded |
book the refund for refund_amount; order_id: null is a card check, skip it |