Refund status in orders
Orders now tell you whether they have been refunded, fully or partially, so that integrations such as ERPs can keep their records in sync with returns handled in OpenTiendas.
Why
Until now, a fully refunded order could not be told apart from a canceled one through the API: both are returned by the is_canceled=true filter, but a fully refunded order has no canceled_at date and no field said that its items had been returned.
refund_status
A new field refund_status is available in orders, following the same pattern as fulfillment_status and warehouse_release_status:
| Value | Meaning |
|---|---|
not_refunded | The order has no completed refunds |
partially_refunded | Some items have been refunded |
refunded | All items have been refunded, including shipping and payment fees. The order will not change anymore |
Only completed refunds are taken into account. A refund that is still pending does not change the status until it is completed.
refunded_at
A new field refunded_at contains the date and time when the order became fully refunded, in ISO 8601 format.
- It is
nullunlessrefund_statusisrefunded, also when the order is only partially refunded. - Once set, it does not change.
- Orders that were fully refunded before this release also have it.
{
"id": 1267,
"fulfillment_status": "fulfilled",
"refund_status": "refunded",
"fulfilled_at": "2026-03-19T15:00:00Z",
"refunded_at": "2026-03-27T10:42:13Z"
}
Both fields are part of the default fields of the order, so they are also included in the payload of the order webhooks (order.created, order.paid, order.fulfilled and order.canceled).
New filters
The order listing accepts new filters:
refund_status: one or more refund statuses, comma-separated.refunded_at_from/refunded_at_to: orders fully refunded within a date range. Use them to fetch only the new full refunds since your last synchronization.- Sorting by
refunded_at(sort=refunded_at_ascorsort=refunded_at_desc).
fulfillment_status and warehouse_release_status now accept several comma-separated values too. A single value works as before.
GET /api/v1/orders/?refund_status=partially_refunded,refunded
GET /api/v1/orders/?refunded_at_from=2026-11-01T00:00:00Z
GET /api/v1/orders/?fulfillment_status=partially_fulfilled,fulfilled
Fully refunded orders and is_canceled
A fully refunded order is closed, like a canceled one: it does not need to be shipped or charged anymore. That is why the is_canceled filter has always returned both, and it keeps doing so:
is_canceled=truereturns canceled and fully refunded orders.is_canceled=falsereturns the rest, so you can keep using it to get the orders that are still pending.
To tell them apart, use refund_status. For example, to get only the canceled orders:
GET /api/v1/orders/?is_canceled=true&refund_status=not_refunded
Fully refunded orders have canceled_at set to null and do not trigger the order.canceled webhook.
Availability
GET /api/v1/orders/GET /api/v1/orders/{id}/- Order webhooks

