Report an order status

POST/api/v1/orders/{id}/statusScope catalogue:sync

The store acknowledges an order, or reports its progress. The first external_id releases Floee's reservation; cancelled or refunded gives stock back.

Request

curlshell

curl -X POST "https://icebot.icebergaisolutions.com/api/v1/orders/b2d4e6f8-1a3c-4e5f-8a9b-0c1d2e3f4a5b/status" \
  -H "Authorization: Bearer $ICEBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"5531","external_status":"processing","status":"paid","source":"woocommerce"}'

Parameters

Name	In	Type	Description
`id` (required)	path	uuid	The Floee order id from GET /api/v1/orders.

Body

Field	Type	Description
`external_id`	string \| number	The store's own order id. Sent once, it links the order for good.
`external_status`	string	The store's word for the status, kept verbatim (processing, completed, fulfilled...).
`status`	pending_payment \| paid \| cancelled \| refunded	Floee's status. When absent it is mapped from external_status.
`source`	api \| woocommerce \| shopify	Which store vocabulary external_status is in. Default api.

Example bodyjson

{
  "external_id": "5531",
  "external_status": "processing",
  "status": "paid",
  "source": "woocommerce"
}

Responses

`200`

Saved. stock_events lists what the stock ledger did; replays are safe.

200 responsejson

{
  "data": {
    "id": "b2d4e6f8-1a3c-4e5f-8a9b-0c1d2e3f4a5b",
    "status": "paid",
    "external_id": "5531",
    "stock_events": [
      "store_ack"
    ]
  }
}

Errors

Every endpoint can also return 401 (missing, unknown or revoked key), 403 (origin not allowed, or the key lacks catalogue:sync) and 429 (rate limited). See Errors.

Status	error	When
`400`	`invalid body`	None of external_id, external_status, status was sent, or status is not one of the four. details lists each problem.
`404`	`not found`	The order is not this key's agent's.
`409`	`this order is already linked to store order ...`	A different external_id was already recorded, or that external_id belongs to another order.
`502`	`status saved, but stock was not settled (...); retry`	The status was written but the stock move failed. Send the same request again.

Source of truth: /api/v1/orders/{id}/status in apps/dashboard/app/api/v1/orders/[id]/status/route.ts.