Skip to main content

Refund status in orders

· 3 min read
Albert Tiñena
Chief Technology Officer (CTO)
David Sancho
Principal Engineer & Technical Architect

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:

ValueMeaning
not_refundedThe order has no completed refunds
partially_refundedSome items have been refunded
refundedAll 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 null unless refund_status is refunded, 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_asc or sort=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=true returns canceled and fully refunded orders.
  • is_canceled=false returns 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

👉 API Reference