From 04098ce002f770a46ba3a149feca6b8c64b55e6e Mon Sep 17 00:00:00 2001 From: Raphael Michel Date: Mon, 15 Feb 2021 17:48:33 +0100 Subject: [PATCH] API: Add docs on order lifecycle --- doc/api/guides/index.rst | 1 + doc/api/guides/order_lifecycle.rst | 56 +++++++++++++++++++++++++++++ doc/images/order_objects.png | Bin 0 -> 69031 bytes doc/images/order_objects.puml | 34 ++++++++++++++++++ 4 files changed, 91 insertions(+) create mode 100644 doc/api/guides/order_lifecycle.rst create mode 100644 doc/images/order_objects.png create mode 100644 doc/images/order_objects.puml diff --git a/doc/api/guides/index.rst b/doc/api/guides/index.rst index ee2859070..b148c4df6 100644 --- a/doc/api/guides/index.rst +++ b/doc/api/guides/index.rst @@ -8,4 +8,5 @@ This part of the documentation contains how-to guides on some special use cases .. toctree:: :maxdepth: 2 + order_lifecycle custom_checkout diff --git a/doc/api/guides/order_lifecycle.rst b/doc/api/guides/order_lifecycle.rst new file mode 100644 index 000000000..6e48582d6 --- /dev/null +++ b/doc/api/guides/order_lifecycle.rst @@ -0,0 +1,56 @@ +Understanding the life cycle of orders +====================================== + +When integrating pretix with other systems, it is important that you understand how orders and related objects +such as order positions, fees, payments, refunds, and invoices work together, in order to react to their changes +properly and map them to processes in your system. + +Order states +------------ + +Generally, an order can be in six states. For compatibility reasons, the ``status`` field only allows four values +and the two remaining states are modeled through the ``require_approval`` field and the number of positions within +an order. The states and their allowed changes are shown in the following graph: + +.. image:: /images/order_states.png + + +Object types +------------ + +Order + One order represents one purchase. It's the main object you interact with and bundles all the other objects + together. Orders can change in many ways during their lifetime, but will never be deleted (unless ``testmode`` + is set to ``true``). + +Order position + An order position represents one product contained in the order. Orders can usually have multiple positions. + There might be a parent-child relation between order positions if one position is an add-on to another position. + Order positions can change in many ways during their lifetime, and can also be removed or added to an order. + +Order fees + A fee represents a charge that is not related to a product. Examples include shipping fees, service fees, and + cancellation fees. + Order fees can change in many ways during their lifetime, and can also be removed or added to an order. + +Order payment + An order payment represents one payment attempt with a specific payment method and amount. An order can have + multiple payments attached. + Order payments have their own state diagram. Apart from their state and their meta information (e.g. used + credit card, …) they usually don't change. They may be added at any time, but will never be deleted. + +Order refund + An order payment represents one refund attempt with a specific payment method and amount. An order can have + multiple refunds attached. + Order refunds have their own state diagram. Apart from their state and their meta information (e.g. used + credit card, …) they usually don't change. They may be added at any time, but will never be deleted. + +Invoice + An invoice represents a legal document stating the contents of an order. While the backend technically allows + to update an invoice in some situations, invoices are generally considered immutable. Once they are issued, + they no longer change. If the order changes substantially (e.g. prices change), an invoice is canceled through + creation of a new invoice with the opposite amount, plus the issuance of a new invoice. + +Here's an example of how they all play together: + +.. image:: /images/order_objects.png diff --git a/doc/images/order_objects.png b/doc/images/order_objects.png new file mode 100644 index 0000000000000000000000000000000000000000..880d0bc779772df74555c71684db852f077adc1d GIT binary patch literal 69031 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

oBDJ-&q+bk>$a}9R7ZB}`ld7S<0k)^` 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%0D?y-gB-s*MCbS|TTU+kAMsTYR5k~?yZZ1hty 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 literal 0 HcmV?d00001 diff --git a/doc/images/order_objects.puml b/doc/images/order_objects.puml new file mode 100644 index 000000000..1e1641a51 --- /dev/null +++ b/doc/images/order_objects.puml @@ -0,0 +1,34 @@ +@startuml + +participant User +collections "OrderPayment\nOrderRefund" as P +collections "Order\nOrderPosition" as O +collections "Invoice\nInvoiceLine" as I + +User -> O: Order placed (€100) +rnote over O #6DD96D: Order A1B2C\nstatus = **n**\ntotal = €100 +O -> P: Payment created +O -> I: Invoice created\n(can also happen later) +rnote over I #6DD96D: Invoice 00001\n€100 +rnote over P #6DD96D: OrderPayment A1B2C-P-1\nstate = **created** +P -> User: Payment details (web, email) +User -> P: Payment performed +rnote over P #EFF46B: OrderPayment A1B2C-P-1\nstate = **confirmed** +P -> O: Order marked as paid +rnote over O #EFF46B: Order A1B2C\nstatus = **p**\ntotal = €100 +User -> O: Data change (e.g. invoice address) +O -> I: Invoice reissued +rnote over I #6DD96D: Invoice 00002\n€-100 +rnote over I #6DD96D: Invoice 00003\n€100 +rnote over O #EFF46B: Order A1B2C\nstatus = **p**\ntotal = €100 +User -> O: Order canceled +rnote over O #EFF46B: Order A1B2C\nstatus = **c** +O -> I: Invoice canceled +rnote over I #6DD96D: Invoice 00004\n€-100 +O -> P: Refund started +rnote over P #6DD96D: OrderRefund\nA1B2C-R-1\nstate = **created** +P -> User: Money sent +rnote over P #EFF46B: OrderRefund\nA1B2C-R-1\nstate = **done** + +@enduml +