******************
Order cancellation
******************
The Order cancellation resource is a special API endpoint by which an order can be cancelled.
This means the order status changes to ``cancelled`` and the order is no longer valid.

Accepted methods
================
* **POST**: Cancel an order.

Constraints
===========
* Cancelling an order requires the cancel permission. This is set by Paylogic.
* Order was created using the same credentials as the ones used to cancel it.
* Order is in a valid state.
* Order does not have an associated payment recorded. Refunds are not supported through the API.

Data
====
======================= ======= =========================================================================
Field name              Type    Description
======================= ======= =========================================================================
order                   String  The uri of the order you wish to cancel.
reason                  String  The reason for cancelling this order.
======================= ======= =========================================================================

POST example
============
.. code-block:: bash

    [POST] https://shopping-api.paylogic.com/ordercancellation/

.. code-block:: javascript

    {
        'order': 'https://shopping-api.paylogic.com/orders/87a2195h3gd162fb35c5a3dbd7bapo1l',
        'reason': 'Reason for cancelling this order.'
    }

Response
--------
.. code-block:: javascript

    {
        "_links": {
            "curies": [
                { "name": "shop", "href": "https://shopping-api-docs.paylogic.com/documentation/{rel}.html", "templated": true, "type": "text/html" },
            ],
            "self": { "href": "https://shopping-api.paylogic.com/orders/87a2195h3gd162fb35c5a3dbd7bapo1l" },
            "profile": { "href": "https://shopping-api-docs.paylogic.com/documentation/orders.html", "type": "text/html" },
            "payment": { "href": "https://payments.paylogic.com?redirect=https://psp.paylogic.com/consumer/123", "type": "text/html" },
            "shop:etickets": { "href": "https://download.paylogic.com/eticket/sdfsdf235r245wsdgfw5235", "type": "text/html" },
            "shop:ordercancellation": { "href": "https://shopping-api.paylogic.com/ordercancellation", "type": "text/html" }
        },
        "uid": "87a2195h3gd162fb35c5a3dbd7bapo1l",
        "reference": "525743",
        "created_date": "2014-05-01T12:15:00Z",
        "status": "cancelled",
        "product_selection": [
            {
                "product": "https://shopping-api.paylogic.com/products/12365478654238976585643567854323",
                "quantity": 3
            },
            {
                "product": "https://shopping-api.paylogic.com/products/456ghtr45tg678fe5rf456yhgbvsw3lh",
                "quantity": 1
            },
            {
                "parent": "https://shopping-api.paylogic.com/products/456ghtr45tg678fe5rf456yhgbvsw3lh",
                "product": "https://shopping-api.paylogic.com/products/267arnr45tg984rd5rf456opshwks0ol",
                "quantity": 1
            }
        ],
        "consumer": {
            "first_name": "John",
            "last_name": "Doe",
            "date_of_birth": "1986-12-30",
            "email": "john.doe@paylogic.eu",
            "gender": 1,
            "address": "Nieuwe Boteringestraat 28",
            "postal_code": "9716 JJ",
            "city": "Groningen",
            "country": "NL",
            "ip": "192.168.1.1"
        },
        "payment_method": {
            "uid": "ghr57d5h3gd162fb35c5a3db57ghrydg",
            "name": {"en": "iDeal", "nl": "", "de": "", "fr": "", "es": "", "pt": "", "tr": "", "ru": ""},
            "image": "https://static.paylogic.com/ideal.jpg",
            "costs": { "amount": 1.00, "currency": "EUR" }
        },
        "shipping_method": {
            "uid": "87a5quvndhe162fb357alt872705zr2j",
            "name": {"en": "Eticket", "nl": "", "de": "", "fr": "", "es": "", "pt": "", "tr": "", "ru": ""},
            "costs": { "amount": 0.50, "currency": "EUR" }
        },
        "product_total": { "amount": 13.50, "currency": "EUR" },
        "service_costs": { "amount": 1.50, "currency": "EUR" },
        "grand_total": { "amount": 16.50, "currency": "EUR" },
        "external_purchases": [
            {
                "title": {"en": "External purchase", "nl": "", "de": "", "fr": "", "es": "", "pt": "", "tr": "", "ru": ""},
                "product_reference": "External purchase product A",
                "unit_price": { "amount": 50.00, "currency": "EUR" },
                "quantity": 3
            }
        ]
        "external_reference": "CO-115",
        "_embedded": {
            "shop:product": [
                // ...
            ],
            "shop:ticket": [
                // ...
            ]
        }
    }

POST error handling
===================
.. _cancel-errors:

Error types
-----------
======================      ===================     ==================================================================
Type                        HTTP Code               Description
======================      ===================     ==================================================================
FORBIDDEN                   403                     Forbidden. No cancel permission or order has a payment.
NOT_FOUND                   404                     Not found. The order was not found.
BAD_REQUEST                 400                     Bad request. This can happen if the uid or reason are missing.
ORDER_ALREADY_CANCELED      409                     Conflict. The order is already canceled.
======================      ===================     ==================================================================