Order states

Every order moves through a fixed set of states. Transitions are one-way — you cannot move an order backward to a previous state through the admin UI or any API.

Autonnel’s responsibility ends at PAID. Everything after — fulfillment, shipping updates, delivery confirmation, refund processing — is owned by your headless ecommerce backend. Autonnel polls the backend on a regular interval and reflects state changes back into its order list. If your backend supports order status webhooks, you can wire them to push changes faster.

State table

State	Who controls the transition	Notes
PENDING	Autonnel (set on order creation)	Default state. Covers both unpaid orders and orders where payment has been authorized but not yet captured (e.g. PayPal authorization-mode).
PAID	Autonnel — when the payment provider confirms capture	Set when Stripe or PayPal reports a successful capture. Also set by the auto-capture job for PayPal authorization-mode payments.
SHIPPED	Your ecommerce backend — autonnel polls and reflects the change	Set when autonnel detects a tracking number on the external ecommerce platform (Shopify, WooCommerce, or Picocart) and the platform has not yet reported delivery.
DELIVERED	Your ecommerce backend or an external API call (POST /api/v1.1/orders/:id/deliver)	Set automatically when the ecommerce platform reports delivery. Also settable via the external deliver endpoint with an API key that has writeAccess.
PARTIALLY_REFUNDED	Your ecommerce backend (or autonnel if you refund via autonnel’s admin UI)	Set when a refund is submitted and the refund total is less than the order total.
REFUNDED	Your ecommerce backend (or autonnel if you refund via autonnel’s admin UI)	Set when cumulative refunds equal or exceed the order total (within a 1-cent tolerance).

Transition details

PENDING to PAID

Payment is captured by the Stripe or PayPal adapter after the customer completes the payment flow. For Stripe, the charge event arrives via the Stripe Elements confirmation callback. For PayPal, the capture call is made server-side after the customer approves the payment.

Auto-capture for authorization-mode payments. When PayPal is configured to authorize rather than capture immediately, the order stays in PENDING. A background job runs on a configurable schedule and captures any authorized payments that have been pending long enough. On success, the order transitions to PAID.

PAID to SHIPPED

Autonnel polls your connected ecommerce platform (Shopify, WooCommerce, or Picocart) every few minutes for each PAID order. When a tracking number is detected and the platform has not yet reported delivery:

1. The order moves to SHIPPED.
2. Tracking number, carrier, and shipment status fields are updated.
3. A shipped notification email is queued for the customer.

If the platform already reports delivery on the same poll, the order moves directly to DELIVERED instead (see below). Orders not connected to an ecommerce platform are not polled and will remain in PAID until you advance them manually.

SHIPPED to DELIVERED

There are two ways an order transitions to DELIVERED:

1. Automatic (backend polling). Autonnel re-checks SHIPPED orders on the same polling interval. When the ecommerce adapter returns a delivered status (mapped from Shopify’s displayStatus, WooCommerce’s status === 'completed', or Picocart’s fulfillment_status === 'fulfilled'), the order moves to DELIVERED and a delivered notification email is queued. A PAID order with delivery already reported on its first poll moves straight to DELIVERED and only the delivered email is sent — the shipped email is skipped.

2. External API. A third-party system (for example, a shipping carrier webhook handler you build) can also move an order manually:

POST /api/v1.1/orders/{orderId}/deliver
Authorization: Bearer <api-key-with-writeAccess>

The endpoint enforces two conditions before updating:

• The API key must have writeAccess enabled.
• The order must currently be in the SHIPPED state. Any other state returns HTTP 409.

On success, the order moves to DELIVERED and a delivered notification email is queued.

PAID / SHIPPED / DELIVERED to PARTIALLY_REFUNDED or REFUNDED

Refunds are initiated from the order detail page in the admin UI (or via the API). The transition depends on how much of the order total has already been refunded:

• If the new cumulative refund total is less than the order total, the order moves to PARTIALLY_REFUNDED.
• If the new cumulative refund total equals or exceeds the order total (within a 1-cent tolerance), the order moves to REFUNDED.

A REFUNDED order cannot be refunded further. Attempting to refund a REFUNDED order returns an error.

See Refunds for the full refund flow.

Caveats

• State transitions are one-way. There is no admin action or API endpoint that moves an order backward (e.g. from SHIPPED back to PAID).
• The PENDING state covers two distinct situations: an unpaid order waiting for the customer to complete payment, and an authorized-but-not-yet-captured PayPal payment. Both display as PENDING in the UI.
• Autonnel only polls for fulfillment on orders connected to an ecommerce platform. If you are not connected, orders will remain in PAID indefinitely and you must use the external DELIVER API or a manual process to advance their state.
• The DELIVER endpoint requires a separate API key with writeAccess. A read-only API key returns HTTP 403.

Related

• Refunds — how refunds affect order state.
• Order emails — emails triggered at each state transition.
• External endpoints — full reference for the external API, including the deliver endpoint.