diff --git a/doc/api/resources/orders.rst b/doc/api/resources/orders.rst
index feffd3def5..df5e00e6d8 100644
--- a/doc/api/resources/orders.rst
+++ b/doc/api/resources/orders.rst
@@ -1948,6 +1948,9 @@ Manipulating individual positions
    Changing parameters such as ``item`` or ``price`` will **not** automatically trigger creation of a new invoice,
    you need to take care of that yourself.
 
+   Changing ``secret`` does not cause a new PDF ticket to be sent to the customer, nor does it cause the old secret
+   to be added to the revocation list, even if your ticket generator uses one.
+
    **Example request**:
 
    .. sourcecode:: http