****************
Refund requests
****************
Refund requests is a resource that contains a collection of :doc:`/objects/refund_request`.


Authentication
--------------
The retrieval of the refund request collection or a single refund request can be authenticated in multiple ways.

- :ref:`order-token`: The token of the order that we want its refunds.
- :ref:`cognito-token`: The user represented by the token must be the creator of the order associated with this refund.

Accepted methods
================
* **GET**: Retrieve the list of refunds.


Accepted query parameters
=========================
========================  ==============================================  ==============================================
Parameter                 Type                                            Description
========================  ==============================================  ==============================================
order                     String                                          URI of the order.
========================  ==============================================  ==============================================


Embedded resources
===================
A collection of :doc:`/objects/refund_request`.


Example representation
======================
.. code-block:: bash

    [GET] https://shopping-api.paylogic.com/refund_requests?order=https://shopping-api.paylogic.com/orders/f6284ab0fd3147e5b6ea40cc0ba1b69a

.. code-block:: javascript

    {
        "_links": {
            "self": {
                "href": "https://shopping-api.paylogic.com/refund_requests"
            },
            "curies": [
                {
                    "href": "https://shopping-api-docs.paylogic.com/documentation/{rel}.html",
                    "name": "shop",
                    "templated": true,
                    "type": "text/html"
                }
            ]
        },
        "_embedded": {
            "shop:refund_requests": [
                {
                    "_links": {
                        "self": {
                            "href": "https://shopping-api.paylogic.com/refund_requests/d026626a0ac64ec1ab4daff8c8b1c345"
                        },
                        "shop:order": {
                            "href": "https://shopping-api.paylogic.com/orders/f6284ab0fd3147e5b6ea40cc0ba1b69a"
                        },
                        "curies": [
                            {
                                "href": "https://shopping-api-docs.paylogic.com/documentation/{rel}.html",
                                "name": "shop",
                                "templated": true,
                                "type": "text/html"
                            }
                        ]
                    },
                    "status": "new",
                    "created_at": "2022-11-14T11:20:23Z",
                    "refund_percentage": "0.00",
                    "change_order_percentage": null,
                    "voucher_percentage": "0.00",
                    "donation_percentage": "1.00",
                    "direct_refundable_amount_breakdown": null,
                    "submitted_bank_details": false,
                    "keep_tickets": false,
                    "source": "event_refund",
                    "_embedded": {
                        "shop:refund_bill": {
                            "_links": {
                                "self": {
                                    "href": "https://shopping-api.paylogic.com/refund-bill?refund_request=b5d33663a7e44f28ad22f43cde57762c"
                                }
                            },
                            "refund_amount": {
                                "amount": "0.00",
                                "currency": "EUR"
                            },
                            "voucher_amount": {
                                "amount": "0.00",
                                "currency": "EUR"
                            }
                        }
                    },
                }
            ]
        }
    }


Retrieve a single refund request
=================================
Retrieve one :doc:`/objects/refund_request` item with the refund request uid.


Embedded resources
==================
* :doc:`/objects/refund_bill`: A partial refund bill object which contains a refund and voucher amounts only.


Example representation
======================
.. code-block:: bash

    [GET] https://shopping-api.paylogic.com/refund_requests/d026626a0ac64ec1ab4daff8c8b1c345

.. code-block:: javascript

    {
        "_links": {
            "self": {
                "href": "https://shopping-api.paylogic.com/refund_requests/d026626a0ac64ec1ab4daff8c8b1c345"
            },
            "shop:order": {
                "href": "https://shopping-api.paylogic.com/orders/f6284ab0fd3147e5b6ea40cc0ba1b69a"
            },
            "curies": [
                {
                    "href": "https://shopping-api-docs.paylogic.com/documentation/{rel}.html",
                    "name": "shop",
                    "templated": true,
                    "type": "text/html"
                }
            ]
        },
        "status": "new",
        "created_at": "2022-11-14T11:20:23Z",
        "refund_percentage": "0.00",
        "change_order_percentage": null,
        "voucher_percentage": "0.00",
        "donation_percentage": "1.00",
        "direct_refundable_amount_breakdown": null,
        "submitted_bank_details": false,
        "keep_tickets": false,
        "source": "event_refund",
        "_embedded": {
            "shop:refund_bill": {
                "_links": {
                    "self": {
                        "href": "https://shopping-api.paylogic.com/refund-bill?refund_request=b5d33663a7e44f28ad22f43cde57762c"
                    }
                },
                "refund_amount": {
                    "amount": "0.00",
                    "currency": "EUR"
                },
                "voucher_amount": {
                    "amount": "0.00",
                    "currency": "EUR"
                }
            }
        },
    }


Create a refund request
=======================
* **POST**: Create a refund request and return in in the response.

Example representation
======================
.. code-block:: bash

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

.. code-block:: javascript

    {
        "_links": {
            "self": {
                "href": "https://shopping-api.paylogic.com/refund_requests/d026626a0ac64ec1ab4daff8c8b1c345"
            },
            "shop:order": {
                "href": "https://shopping-api.paylogic.com/orders/f6284ab0fd3147e5b6ea40cc0ba1b69a"
            },
            "curies": [
                {
                    "href": "https://shopping-api-docs.paylogic.com/documentation/{rel}.html",
                    "name": "shop",
                    "templated": true,
                    "type": "text/html"
                }
            ]
        },
        "status": "new",
        "created_at": "2022-11-14T11:20:23Z",
        "refund_percentage": "0.00",
        "change_order_percentage": null,
        "voucher_percentage": "0.00",
        "donation_percentage": "1.00",
        "direct_refundable_amount_breakdown": null,
        "submitted_bank_details": false,
        "keep_tickets": false,
        "source": "event_refund",
        "_embedded": {
            "shop:refund_bill": {
                "_links": {
                    "self": {
                        "href": "https://shopping-api.paylogic.com/refund-bill?refund_request=b5d33663a7e44f28ad22f43cde57762c"
                    }
                },
                "refund_amount": {
                    "amount": "0.00",
                    "currency": "EUR"
                },
                "voucher_amount": {
                    "amount": "0.00",
                    "currency": "EUR"
                }
            }
        },
    }


Update a refund request
=======================
* **PUT**: Update a refund request and return it in the response

Example representation
======================
.. code-block:: bash

    [PUT] https://shopping-api.paylogic.com/refund_requests/d026626a0ac64ec1ab4daff8c8b1c345

.. code-block:: javascript

    {
        "_links": {
            "self": {
                "href": "https://shopping-api.paylogic.com/refund_requests/d026626a0ac64ec1ab4daff8c8b1c345"
            },
            "shop:order": {
                "href": "https://shopping-api.paylogic.com/orders/f6284ab0fd3147e5b6ea40cc0ba1b69a"
            },
            "curies": [
                {
                    "href": "https://shopping-api-docs.paylogic.com/documentation/{rel}.html",
                    "name": "shop",
                    "templated": true,
                    "type": "text/html"
                }
            ]
        },
        "status": "new",
        "created_at": "2022-11-14T11:20:23Z",
        "refund_percentage": "0.00",
        "change_order_percentage": null,
        "voucher_percentage": "0.00",
        "donation_percentage": "1.00",
        "direct_refundable_amount_breakdown": null,
        "submitted_bank_details": false,
        "keep_tickets": false,
        "source": "event_refund",
        "_embedded": {
            "shop:refund_bill": {
                "_links": {
                    "self": {
                        "href": "https://shopping-api.paylogic.com/refund-bill?refund_request=b5d33663a7e44f28ad22f43cde57762c"
                    }
                },
                "refund_amount": {
                    "amount": "0.00",
                    "currency": "EUR"
                },
                "voucher_amount": {
                    "amount": "0.00",
                    "currency": "EUR"
                }
            }
        },
    }