Cancel order

Requires an active API credential with the orders:create permission.

Cancels any order in the store that is not final (processing, action_required, or failed) while no fulfillment attempt or provider request is running and no shipment has left. Looking an order up by merchant_order_ref only finds orders created through the API. Repeating a cancellation that succeeded returns 200 again; an order canceled another way returns 409 with order_already_terminal.

A 409 order_not_cancelable response means the order is not eligible and includes a machine-readable details.reason_code.

Sandbox credentials receive a forbidden response because sandbox orders are stateless.

POST

https://cardzone.ai/api/b2b/v1/orders/{id}/cancel

Authorization

BearerAuth
HTTP
required

Path parameters

id
string
required
Pass the Cardzone order_id returned by the API. A legacy full order UUID or the merchant_order_ref supplied on create is also accepted.

Returns

200

Order canceled

JSON

order_id
string
required
Cardzone order identifier. This is a reversible Base58 representation of the internal UUID.

maxLength: 22 · minLength: 22 · pattern: ^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
status
processing
or
fulfilled
or
action_required
or
failed
or
canceled
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.
product_id
string
or null
required
format: uuid
quantity
integer
required
actions
array of
object
required
Actions required from the API consumer. Empty when no action is needed.
- type
  wallet
  or
  fulfillment
  required
- code
  wallet_topup_required
  or
  merchant_attention_required
  or
  manual_review_required
  required
  Machine-readable action the API consumer should handle.
- 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.
}
created_at
string
required
format: date-time
merchant_order_ref
optional
string
or null
Merchant order reference supplied on create, when present.
product_code
optional
string
or null
purchase_price
optional
object
- amount
  string
  required
  Decimal amount as a string
- currency
  string
  required
}
recommended_retail_price
optional
object
- amount
  string
  required
  Decimal amount as a string
- currency
  string
  required
}
code
optional
string
or null
First delivered voucher code/PIN when available
codes
optional
array of
string
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
optional
string
or null
Backward-compatible human-readable failure summary. Provider messages and responses are never exposed here.
failure_code
optional
fulfillment_failed
or
player_id_incorrect
or null
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.

401

Missing, revoked, or unknown API key. A live key also gets this while its store is inactive, or until the store's business verification is approved and its primary user's email is verified.

JSON

error
object
required
- code
  string
  required
- message
  string
  required
- details
  optional
  unknown
  Optional field-level validation details
- product_status
  optional
  out_of_stock
  or
  unavailable
  Present on 404 product errors when the product exists but cannot be ordered: out_of_stock or unavailable, with the same meaning as the catalog status. Absent when the product id is unknown or deleted.
}

403

The API credential lacks permission, or a sandbox credential was used.

JSON

error
object
required
- code
  string
  required
- message
  string
  required
- details
  optional
  unknown
  Optional field-level validation details
- product_status
  optional
  out_of_stock
  or
  unavailable
  Present on 404 product errors when the product exists but cannot be ordered: out_of_stock or unavailable, with the same meaning as the catalog status. Absent when the product id is unknown or deleted.
}

404

Order was not found

JSON

error
object
required
- code
  string
  required
- message
  string
  required
- details
  optional
  unknown
  Optional field-level validation details
- product_status
  optional
  out_of_stock
  or
  unavailable
  Present on 404 product errors when the product exists but cannot be ordered: out_of_stock or unavailable, with the same meaning as the catalog status. Absent when the product id is unknown or deleted.
}

409

Order cannot be canceled

JSON

error
object
required
- code
  string
  required
- message
  string
  required
- details
  optional
  unknown
  Optional field-level validation details
- product_status
  optional
  out_of_stock
  or
  unavailable
  Present on 404 product errors when the product exists but cannot be ordered: out_of_stock or unavailable, with the same meaning as the catalog status. Absent when the product id is unknown or deleted.
}