API: Expose cancellation_date on order endpoint (Z#23170733) (#4606)

Co-authored-by: robbi5 <richt@rami.io>

doc/api/resources/orders.rst

@@ -104,6 +104,10 @@ url                                   string                     The full URL to
 payments                              list of objects            List of payment processes (see below)
 refunds                               list of objects            List of refund processes (see below)
 last_modified                         datetime                   Last modification of this object
+cancellation_date                     datetime                   Time of order cancellation (or ``null``). **Note**:
+                                                                 Will not be set for partial cancellations and is not
+                                                                 reliable for orders that have been cancelled,
+                                                                 reactivated and cancelled again.
 ===================================== ========================== =======================================================
 
 
@@ -151,6 +155,9 @@ last_modified                         datetime                   Last modificati
 
    The ``expires`` attribute can now be passed during order creation.
 
+.. versionchanged:: 2024.11
+
+   The ``cancellation_date`` attribute has been added and can also be used as an ordering key.
 
 .. _order-position-resource:
 
@@ -464,14 +471,15 @@ List of all orders
                 "provider": "banktransfer"
               }
             ],
-            "refunds": []
+            "refunds": [],
+            "cancellation_date": null
           }
         ]
       }
 
    :query integer page: The page number in case of a multi-page result set, default is 1
    :query string ordering: Manually set the ordering of results. Valid fields to be used are ``datetime``, ``code``,
-                           ``last_modified``, and ``status``. Default: ``datetime``
+                           ``last_modified``, ``status`` and ``cancellation_date``. Default: ``datetime``
    :query string code: Only return orders that match the given order code
    :query string status: Only return orders in the given order status (see above)
    :query string search: Only return orders matching a given search query (matching for names, email addresses, and company names)
@@ -703,7 +711,8 @@ Fetching individual orders
             "provider": "banktransfer"
           }
         ],
-        "refunds": []
+        "refunds": [],
+        "cancellation_date": null
       }
 
    :param organizer: The ``slug`` field of the organizer to fetch

src/pretix/api/serializers/order.py

@@ -753,12 +753,12 @@ class OrderSerializer(I18nAwareModelSerializer):
             'code', 'event', 'status', 'testmode', 'secret', 'email', 'phone', 'locale', 'datetime', 'expires', 'payment_date',
             'payment_provider', 'fees', 'total', 'comment', 'custom_followup_at', 'invoice_address', 'positions', 'downloads',
             'checkin_attention', 'checkin_text', 'last_modified', 'payments', 'refunds', 'require_approval', 'sales_channel',
-            'url', 'customer', 'valid_if_pending', 'api_meta'
+            'url', 'customer', 'valid_if_pending', 'api_meta', 'cancellation_date'
         )
         read_only_fields = (
             'code', 'status', 'testmode', 'secret', 'datetime', 'expires', 'payment_date',
             'payment_provider', 'fees', 'total', 'positions', 'downloads', 'customer',
-            'last_modified', 'payments', 'refunds', 'require_approval', 'sales_channel'
+            'last_modified', 'payments', 'refunds', 'require_approval', 'sales_channel', 'cancellation_date'
         )
 
     def __init__(self, *args, **kwargs):

src/pretix/api/views/order.py

@@ -215,7 +215,7 @@ class OrderViewSetMixin:
     queryset = Order.objects.none()
     filter_backends = (DjangoFilterBackend, TotalOrderingFilter)
     ordering = ('datetime',)
-    ordering_fields = ('datetime', 'code', 'status', 'last_modified')
+    ordering_fields = ('datetime', 'code', 'status', 'last_modified', 'cancellation_date')
     filterset_class = OrderFilter
     lookup_field = 'code'
 

src/tests/api/test_order_create.py

@@ -492,6 +492,7 @@ def test_order_create_simulate(token_client, organizer, event, item, quota, ques
         'refunds': [],
         'require_approval': False,
         'sales_channel': 'web',
+        'cancellation_date': None
     }
 
 

src/tests/api/test_orders.py

@@ -337,6 +337,7 @@ TEST_ORDER_RES = {
     "downloads": [],
     "payments": TEST_PAYMENTS_RES,
     "refunds": TEST_REFUNDS_RES,
+    "cancellation_date": None,
 }