---
title: "OrderStatusResponse"
---

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

# OrderStatusResponse

Path: Cardzone B2B API

Live responses omit keys that have no value instead of sending `null`.

## Fields

- `order_id` (`OrderStatusResponse.order_id`; string, required) — Cardzone order identifier. This is a reversible Base58 representation of the internal UUID.
  - minLength 22; maxLength 22; pattern `^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$`
- `status` (`OrderStatusResponse.status`; string, required) — `processing`: accepted or still fulfilling. `fulfilled`: successful; safe to mark the partner order successful. `action_required`: inspect `actions` and take the required action. `failed`: terminal failure; inspect `failure_reason` when present. Replacement codes the store paid for can still be added to `codes`, and a dashboard retry moves the order back to `processing`. `canceled`: terminal cancellation; no fulfillment action remains.
  - one of `"processing"`, `"fulfilled"`, `"action_required"`, `"failed"`, `"canceled"`
- `product_id` (`OrderStatusResponse.product_id`; string, required, nullable)
  - format `uuid`
- `quantity` (`OrderStatusResponse.quantity`; integer, required)
- `actions` (`OrderStatusResponse.actions`; array<object>, required) — Actions required from the API consumer. Empty when no action is needed.
  - `type` (`OrderStatusResponse.actions.type`; string, required)
    - one of `"wallet"`, `"fulfillment"`
  - `code` (`OrderStatusResponse.actions.code`; string, required) — Machine-readable action the API consumer should handle.
    - one of `"wallet_topup_required"`, `"merchant_attention_required"`, `"manual_review_required"`
  - `message` (`OrderStatusResponse.actions.message`; string, required) — Human-readable action summary. Wallet actions include the aggregate additional top-up amount needed for all current wallet-blocked orders in the store.
    - example `"Recharge 75 SAR to resume fulfillment for all wallet-blocked orders."`
- `created_at` (`OrderStatusResponse.created_at`; string, required)
  - format `date-time`
- `merchant_order_ref` (`OrderStatusResponse.merchant_order_ref`; string, optional, nullable) — Merchant order reference supplied on create, when present.
- `product_code` (`OrderStatusResponse.product_code`; string, optional, nullable)
- `purchase_price` (`OrderStatusResponse.purchase_price`; object, optional)
  - `amount` (`OrderStatusResponse.purchase_price.amount`; string, required) — Decimal amount as a string
    - example `"12.00"`
  - `currency` (`OrderStatusResponse.purchase_price.currency`; string, required)
    - example `"SAR"`
- `recommended_retail_price` (`OrderStatusResponse.recommended_retail_price`; object, optional)
  - `amount` (`OrderStatusResponse.recommended_retail_price.amount`; string, required) — Decimal amount as a string
    - example `"12.00"`
  - `currency` (`OrderStatusResponse.recommended_retail_price.currency`; string, required)
    - example `"SAR"`
- `code` (`OrderStatusResponse.code`; string, optional, nullable) — First delivered voucher code/PIN when available
- `codes` (`OrderStatusResponse.codes`; array<string>, optional) — All delivered voucher codes/PINs when available. Includes replacement codes Cardzone delivered and charged to the store, which can appear while `status` is `failed`.
- `failure_reason` (`OrderStatusResponse.failure_reason`; string, optional, nullable) — Backward-compatible human-readable failure summary. Provider messages and responses are never exposed here.
- `failure_code` (`OrderStatusResponse.failure_code`; string, optional, nullable) — Cardzone-owned terminal failure identifier. `fulfillment_failed` is the generic failure and `player_id_incorrect` means the submitted player ID was definitively rejected. Provider messages and responses are never exposed here.
  - one of `"fulfillment_failed"`, `"player_id_incorrect"`


Source: https://docs.cardzone.ai/reference/schemas/OrderStatusResponse/index.md