POST /v1/catalogue/orders/{order_id}/decline

Decline an order, and tell the customer why if you give a reason.

Declines an order. A reason, when given, is sent to the customer on the channel the order came in on; without one, nothing is sent. A declined order can’t be fulfilled. Webhooks get order.declined. Asking again for the status it already has changes nothing and sends nothing.

Needs the catalogue.orders:write scope.

Path parameters

Field	Type	Required	Notes
order_id	string	Yes	The order’s id.

Body

Field	Type	Required	Notes
reason	string	No	What to tell the customer. Up to 1,000 characters.

Request

cURL

curl -X POST "https://api.fireflo.au/v1/catalogue/orders/9d4e2b7a-1c3f-4a8e-b6d5-0f2e7c9a1b34/decline" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Sorry — the indigo kurta in M is sold out. We'll message you when it's back."
}'

Response

200 OK — the order, now declined. status is new, confirmed, declined, fulfilled or cancelled. source is where it came from: cart (a WhatsApp cart), agent (an AI agent’s draft, approved by a person), person (made by hand in the panel) or api. channel is the channel it came in on, where replies about it go. Each line keeps its own copy of the name and price, so a later change to the product doesn’t rewrite it; product is the product’s id, or null for a SKU the catalogue doesn’t have. Money is in minor units.

{
  "id": "9d4e2b7a-1c3f-4a8e-b6d5-0f2e7c9a1b34",
  "number": 1043,
  "status": "declined",
  "source": "api",
  "channel": "whatsapp",
  "contact": {
    "id": "5b2f9e1c-8a3d-4c7e-9f61-2d4b7a0e3c85",
    "name": "Asha Menon",
    "phone": "[phone]"
  },
  "items": [
    {
      "product": "3f8a2c1e-7b4d-4e6a-9c2f-1a5b8d7e6f40",
      "sku": "KUR-COT-IND-M",
      "name": "Cotton kurta — indigo, M",
      "quantity": 2,
      "unit_price_minor": 199900
    },
    {
      "product": "a71c5e93-2d8b-4f16-8e0a-6b9d3c2f1e57",
      "sku": "DUP-PHUL-RED",
      "name": "Phulkari dupatta — red",
      "quantity": 1,
      "unit_price_minor": 179900
    }
  ],
  "total_minor": 579700,
  "currency": "INR",
  "note": "Gift wrap, please.",
  "created_at": "2026-10-06T11:08:37+05:30",
  "updated_at": "2026-10-06T11:15:02+05:30"
}

Errors

Every refusal is {"error": {"code", "message", "field"}}; field is there when one input is at fault.

Status	Error code	When
404	not_found	No order of this account’s has that id.
404	module_off	The account doesn’t have Catalogue on.
403	scope_missing	The key doesn’t have the catalogue.orders:write scope.

Any request can also be refused for its key, its account or its rate (key_required, invalid_key, account_suspended, plan_excludes_api, address_not_allowed, rate_limited); see the overview.