Statuses
Order statuses
Section titled “Order statuses”| Status | Meaning |
|---|---|
draft |
The cart. The shop server may still replace the items; the widget collects contact and delivery. |
pending_payment |
The shopper pressed “Go to payment”: a payment exists, the items are frozen. Checking out again creates a new payment attempt; the status does not change. |
paid |
Payment succeeded. Subscriptions created, emails sent. Nothing changes after this. |
cancelled |
Cancelled from a panel (from draft or pending_payment). Final. |
Transitions: draft → pending_payment → paid; cancelled is reachable from draft and pending_payment. There is no way back: an order never returns from pending_payment to draft, even when the payment failed.
What is allowed in which status
Section titled “What is allowed in which status”| Action | draft |
pending_payment |
paid |
cancelled |
|---|---|---|---|---|
The shop server replaces the items (PUT /v1/shop/orders/{order}/items) |
200 | 409 | 409 | 409 |
| The shopper changes contact and delivery in the widget | yes | yes | no | no |
| The shopper starts the payment in the widget | yes | yes (a new attempt) | no — the success screen is shown | no — “Checkout unavailable” |
An unknown order or another shop’s order is always 404. The widget always opens an unfinished order («Draft», «Awaiting payment»). A paid or cancelled one opens only within 24 hours of its last change; an older one counts as gone (neocarts:order-missing). The Shop API has no such limit.
409/422 error texts (message)
Section titled “409/422 error texts (message)”The language follows Accept-Language. Build logic on the status code, not on the text.
| Key | uk | en |
|---|---|---|
already_paid |
Це замовлення вже оплачене. | This order has already been paid. |
cancelled |
Це замовлення скасовано. | This order has been cancelled. |
not_editable |
Оплачене замовлення змінити не можна. | A paid order can no longer be changed. |
items_frozen |
Товари замовлення, яке вже в оформленні, змінити не можна. | The items of an order in checkout can no longer be changed. |
checkout_incomplete (422) |
Перед оформленням треба зберегти контакти та доставку. | The contact and delivery steps have to be saved before checkout. |
payments_unavailable (422) |
Цей магазин не може приймати оплату. | This shop cannot take payments. |
| line validation (422) | У замовленні має бути щонайменше один товар за підпискою. | An order has to hold at least one subscription item. |
Why a payment did not go through
Section titled “Why a payment did not go through”When a payment fails, the widget shows the shopper one of these texts and offers to try again. The shop server does nothing: the order stays pending_payment until the shopper pays.
| Reason | uk | en | What next |
|---|---|---|---|
payment_failed |
Оплату відхилено. Спробуйте ще раз, за потреби іншою карткою. | The payment was declined. Try again, with another card if needed. | The shopper pays again. |
payment_expired |
Термін дії сторінки оплати минув. Розпочніть оплату знову. | The payment page has expired. Start the payment again. | The shopper pays again. |
card_not_saved |
Оплата пройшла, але картку не вдалося зберегти для підписки, тому кошти повернуто. Будь ласка, оплатіть ще раз іншою карткою. | The payment went through but the card could not be saved for the subscription, so the money has been sent back. Please pay again with another card. | The money is already refunded; the shopper pays with another card. |
cancelled |
Це замовлення скасовано. | This order has been cancelled. | The shop server creates a new order. |
Subscription statuses
Section titled “Subscription statuses”| Status | Meaning |
|---|---|
active |
Charged on schedule. Created only after the first payment succeeds. |
paused |
No charges. Paused manually from a panel (optionally with a paused_until date), by the shopper themselves (always with a date) or automatically by the system. |
cancelled |
Stopped — from a panel with a stated reason, or by the shopper themselves (the reason is optional). Can be reactivated from a panel only. |
Allowed transitions: active → paused, active → cancelled, paused → active, paused → cancelled, cancelled → active. Anything else fails with A subscription cannot move from ":from" to ":to". A cancelled subscription has no schedule to change — reactivate it first.
Pause reasons (status_reason)
Section titled “Pause reasons (status_reason)”| Value | When | Panel text (en) |
|---|---|---|
charge_failed |
Fifth consecutive failed charge. | The card was declined five days in a row. The customer can attach another card in their Neocarts account and resume. |
no_card |
No usable card: no token saved, token belongs to another provider, or the shop cannot take payments. | No saved card to charge. The customer can attach a card in their Neocarts account and resume. |
| free text | Pause set manually by the merchant. | Whatever the merchant typed. |
null |
Pause set by the shopper themselves (reason_key: "customer" in the webhook). |
— |
Retry details are in Billing. Cancellation reasons are in Enums.
Payment statuses
Section titled “Payment statuses”| Status | Meaning |
|---|---|
pending |
Invoice issued, no result yet. |
failed |
The provider declined the payment. |
expired |
The payment page expired (or a subscription charge stayed pending for more than a day and was not confirmed). |
success |
Payment received. |
refunded |
Fully refunded; refunded_amount is the source of truth for the amount. |
The status only moves one way — a ratchet: pending < failed / expired < success < refunded. A late confirmation from the provider can turn expired into success, but success never becomes failed. One attempt is one payment; checking out again creates a new record.