---
title: "Handle action_required"
description: "Read actions[] to see why an order is paused, alert the right people, and keep the customer informed."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.cardzone.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle action_required

This page shows how to handle an order whose status is `action_required`. If you haven't yet, read [Order lifecycle](https://docs.cardzone.ai/concepts/order-lifecycle/) first.

`action_required` means the order is paused. It is not lost. Each entry in `actions[]` says why the order is paused.

- Your code MUST make decisions based on `type` and `code`.
- NEVER parse `message`. It is text for people, and it can change or be translated.

## Try each action

Pick a scenario. The sandbox returns the same `actions[]` shape that a live order returns:

## What each action means

wallet · wallet\_topup\_required

Your store wallet could not pay for fulfillment. `message` gives the **total** amount to recharge for all wallet-blocked orders in the store. For example: *"Recharge 50 SAR to resume fulfillment for all wallet-blocked orders."*

What to do: alert the person who recharges the store wallet, and tell the customer there is a short delay. After the store wallet is recharged, fulfillment continues without any more API calls. You get a `status_changed` webhook as the order moves on.

fulfillment · merchant\_attention\_required

Fulfillment has not delivered within 15 minutes. Open the order in the Cardzone dashboard to see what is pending. If it stays blocked, contact Cardzone support and give them the `order_id`.

fulfillment · manual\_review\_required

Cardzone is reviewing the order before it continues. You don't need to send anything. Keep the customer informed, and keep polling or listening for webhooks. The review ends in `fulfilled`, `failed`, or another status.

## Example handler

This function runs for every order update, from a webhook or a poll:

```js
function onOrderUpdate(order) {
  switch (order.status) {
    case "fulfilled":
      return markPaidAndDeliver(order);
    case "failed":
      return notifyFailure(order, order.failure_code);
    case "canceled":
      return releaseOrder(order);
    case "action_required":
      for (const action of order.actions) {
        if (action.code === "wallet_topup_required") alertFinance(action.message);
        else if (action.code === "manual_review_required") continue; // nothing to do but wait
        else alertSupport(order.order_id, action.message); // merchant_attention_required, or a code you don't know yet
      }
      return showDelayed(order);
    default:
      return showPending(order); // processing
  }
}
```

> **Plan for action codes you don't know**
>
> If you get a `code` you don't know, handle it like `merchant_attention_required`: alert a person. Cardzone treats a new action code as a breaking change and announces it first. But this safe default protects your integration if a new code ever reaches you.

Source: https://docs.cardzone.ai/guides/action-required/index.mdx