docs

doc/api/resources/orders.rst

@@ -117,6 +117,7 @@ cancellation_date                     datetime                   Time of order c
                                                                  reliable for orders that have been cancelled,
                                                                  reactivated and cancelled again.
 plugin_data                           object                     Additional data added by plugins.
+use_gift_cards                        list of strings            List of gift card secrets that are used to pay for this order.
 ===================================== ========================== =======================================================
 
 
@@ -987,8 +988,6 @@ Creating orders
 
        * does not support file upload questions
 
-       * does not support redeeming gift cards
-
        * does not support or validate memberships
 
 
@@ -1095,6 +1094,15 @@ Creating orders
      whether these emails are enabled for certain sales channels. If set to ``null``, behavior will be controlled by pretix'
      settings based on the sales channels (added in pretix 4.7). Defaults to ``false``.
      Used to be ``send_mail`` before pretix 3.14.
+   * ``use_gift_cards`` (optional) The provided gift cards will be used to pay for this order, they will be debited and
+     all required payment records for these transactions will be created. The gift cards will be used in sequence to pay for
+     the order. Gift cards that cannot be used are skipped. Processing of the gift cards stops as soon as the order is payed.
+     All gift card transactions are listed under ``payments`` in the response.
+     This option can only be used with orders that are in the pending state.
+     You can provide ``payment_info`` and ``payment_provider`` fields in addition to ``use_gift_cards``. A matching
+     payment record for the ``payment_provider`` will be created after all gift cards have been processed. The amount of
+     this entry is the remaining amount you'll need to charge your customer with. The above mentioned caveats for
+     ``payment_info`` still apply.
 
    If you want to use add-on products, you need to set the ``positionid`` fields of all positions manually
    to incrementing integers starting with ``1``. Then, you can reference one of these

src/tests/api/test_order_create.py

@@ -3499,17 +3499,23 @@ def test_order_create_use_multiple_gift_cards(token_client, organizer, event, it
 
     with scopes_disabled():
         o = Order.objects.get(code=resp.data['code'])
+        # order has a payment entry per giftcard
         assert o.status == Order.STATUS_PAID
         assert o.payments.count() == 4
 
-        assert gc_one_eur.transactions.count() == 2
+        assert gc_one_eur.transactions.count() == 2  # +1€ charge and -1€ payment
         assert o.payments.all()[0].state == OrderPayment.PAYMENT_STATE_CONFIRMED
-        assert gc_empty.transactions.count() == 0
+        assert Decimal(-1.00) == gc_one_eur.transactions.last().value
+
+        assert gc_empty.transactions.count() == 0  # no charge and no payment transaction
         assert o.payments.all()[1].state == OrderPayment.PAYMENT_STATE_FAILED
-        assert gc_wrong_currency.transactions.count() == 1
+
+        assert gc_wrong_currency.transactions.count() == 1  # charge transaction
         assert o.payments.all()[2].state == OrderPayment.PAYMENT_STATE_FAILED
-        assert gc_enough_eur.transactions.count() == 2
+
+        assert gc_enough_eur.transactions.count() == 2  # +100€ charge and -remainder € payment
         assert o.payments.all()[3].state == OrderPayment.PAYMENT_STATE_CONFIRMED
+        assert -(o.total - Decimal(1.00)) == gc_enough_eur.transactions.last().value
 
 
 @pytest.mark.django_db