*************
Subscriptions
*************

Some events may require their fans to buy a subscription as well as a regular ticket.
Subscriptions can be purchased the same way as regular products.
Subscriptions are activated when a fan claims a product providing membership.

Retrieve all subscriptions for a user
=====================================
You can retrieve all subscriptions for a user. This resource does not allow any filtering and it will return both valid
and invalid subscriptions. You need to authenticate this call with a :ref:`cognito-token`.

.. code-block:: bash

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

Response
--------
==================== =============================================== ===================================================
Field name           Type                                            Description
==================== =============================================== ===================================================
subscription         :doc:`/objects/subscription` list               One or more subscriptions.
==================== =============================================== ===================================================

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

    {
        "_links": {
            "curies": [
                {
                    "href": "https://shopping-api-docs.paylogic.com/documentation/{rel}.html",
                    "type": "text/html",
                    "name": "shop",
                    "templated": true
                }
            ],
            "self": {
                "href": "https://shopping-api.paylogic.com/subscriptions"
            },
            "profile": {
                "href": "https://shopping-api-docs.paylogic.com/documentation/subscriptions.html",
                "type": "text/html"
            }
        },
        "_embedded": {
            "shop:subscription": [
                {
                    "_links": {
                        "profile": {
                            "href": "https://shopping-api-docs.paylogic.com/documentation/subscription.html",
                            "type": "text/html"
                        },
                        "curies": [
                            {
                                "href": "https://shopping-api-docs.paylogic.com/documentation/{rel}.html",
                                "type": "text/html",
                                "name": "shop",
                                "templated": true
                            }
                        ],
                        "self": {
                            "href": "https://shopping-api.paylogic.com/subscriptions/3c7371e78a7e4c8d91b5569595f09b93"
                        },
                        "shop:provided_by_ticket": {
                            "href": "https://shopping-api.paylogic.com/tickets/3c7371e78a7e4c8d91b5569595f09b93"
                        }
                    },
                    "is_active": true,
                    "canceled_at": null,
                    "expires_at": "2020-08-23T12:44:27Z",
                    "membership": {
                        "uid": "6283a17ed4f940bf924277f702ba3758",
                        "name": {"en": "Monthly Gold subscription", "nl": "Maandelijkse Gold abonnement", /* ... */}
                    }
                },
                // ... more subscriptions
            ]
        }
    }


Retrieve a single subscription
==============================
Retrieve the details for a single subscription.
Authenticate this request with a :ref:`cognito-token` for the user that owns the subscription, or using
:ref:`basic-auth` for the application that created the order containing the subscription.

.. code-block:: bash

    [GET] https://shopping-api.paylogic.com/subscriptions/3c7371e78a7e4c8d91b5569595f09b93

.. code-block:: javascript

    {
        "_links": {
            "profile": {
                "href": "https://shopping-api-docs.paylogic.com/documentation/subscription.html",
                "type": "text/html"
            },
            "curies": [
                {
                    "href": "https://shopping-api-docs.paylogic.com/documentation/{rel}.html",
                    "type": "text/html",
                    "name": "shop",
                    "templated": true
                }
            ],
            "self": {
                "href": "https://shopping-api.paylogic.com/subscriptions/3c7371e78a7e4c8d91b5569595f09b93"
            },
            "shop:provided_by_ticket": {
                "href": "https://shopping-api.paylogic.com/tickets/3c7371e78a7e4c8d91b5569595f09b93"
            }
        },
        "is_active": true,
        "canceled_at": null,
        "expires_at": "2020-08-23T12:44:27Z",
        "membership": {
            "uid": "6283a17ed4f940bf924277f702ba3758",
            "name": {"en": "Monthly Gold subscription", "nl": "Maandelijkse Gold abonnement", /* ... */}
        }
    }


Cancel a subscription
=====================

Subscriptions with a recurring payment can be canceled.
This cancellation cannot be undone, you will have to create a new subscription.

Authenticate this request with a :ref:`cognito-token` for the user that owns the subscription, or using
:ref:`basic-auth` for the application that created the order containing the subscription.

After cancellation, the subscription will remain active until the moment the subscription would have been renewed (``expires_at``).

.. code-block:: bash

    [PUT] https://shopping-api.paylogic.com/subscriptions/d49f7143ba484f988afe13a5d328eb46

.. code-block:: javascript

    { "is_canceled": true }

The API will respond with an updated subscription:

.. code-block:: javascript

    {
        "_links": {
            /* ... */
        },
        "is_active": true,
        "canceled_at": "2021-05-18T12:22:22Z",
        "expires_at": "2021-05-25T15:00:00Z",
        "membership": {
            "uid": "d49f7143ba484f988afe13a5d328eb46",
            "name": {
                "en": "Streaming package",
                "nl": "Streaming pakket",
            }
        }
    }