Skip to content

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.

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 filled

order.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.

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: false

subscription.renewed carries the order_id of that order and previous_next_charge_at. A renewal order has one line — this subscription.

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 day
attempt 2 payment.failed attempt: 2, next_attempt_at: +1 day
attempt 3 payment.failed attempt: 3, next_attempt_at: +1 day
attempt 4 payment.failed attempt: 4, next_attempt_at: +1 day
attempt 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: null

There 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.

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.

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 snapshot
change 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_price
confirm payment by hand order.paid payment: null, confirmed_manually: true
close an order order.cancelled draft or pending_payment
refund payment.refunded refund_amount is this refund

Bulk 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.

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: null

The same event as a manual resume; paused_until in the snapshot is always null after a resume.

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 set
resume from a pause subscription.resumed previous_status: "paused"
cancel subscription.cancelled cancellation_reason in the snapshot, or null
another address subscription.updated changed: ["delivery"]
edit a saved address subscription.updated changed: ["delivery"], one per subscription on the address
replace the card subscription.updated changed: ["card"]
payment.refunded order_id: null, the 1 ₴ refund

A 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.

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