Paywall API
===========

Our Paywall API provides access to subscription management.

All access to paid content is managed through subscriptions and attached email qualifiers.

Access to requested pages is granted when a subscription with a matching email qualifier exists.

Email qualifier
***************
==================== ========================
Email Qualifier      Description
==================== ========================
``user@company.com`` Personal email qualifier
``@company.com``     Group email qualifier
==================== ========================

Authorization
-------------

Authentication for Paywall API endpoints is implemented via sessions.
A ``sessionid`` with the correct session token is required.
The paywall uses an internal Permissions API for authorization.

Data
----

Subscription
************

=========================== ================= ============================================================
Name                        Type              Description
=========================== ================= ============================================================
``id``                      Integer           Subscription ID
``account``                 Object            Account object
``name``                    String            Subscription name
``subscription_type``       Integer           Type of subscription (see below)
``date_start``              String            Activation date
``date_expire``             String            Expiration date
``max_member``              Integer           Maximum number of members of group subscription
``status_active``           Boolean           Activation status
``status_count_of_member``  Integer           Current number of all members
``status_inactive_member``  Integer           Current number of inactive members
``status_active_member``    Integer           Current number of active members
``status_login_count``      Integer           Number of login via subscription
``company_name``            String            Company name of group subscription
``email_domain``            List              List of email qualifiers
=========================== ================= ============================================================

.. note::

   Subscription types are individual and group


.. note::

   Date format is ``%Y%m%dT%H%M%S``


Account
*******

=========================== ================= ============================================================
Name                        Type              Description
=========================== ================= ============================================================
``id``                      Integer           Account ID (matches Roar ID)
``name``                    String            Account name
``type``                    String            Account type
=========================== ================= ============================================================


Read subscription
-----------------

Get detailed information about subscription.

Endpoint:

.. code::

   GET /core/paywall/subscriptions/<subscription_id>

Response example:

.. code::

   {
     "account": 1,
     "name": "RebelMouse",
     "subscription_type": 1,
     "status_active": true,
     "status_count_of_member": 100,
     "email_domain": [
       "@rebelmouse.com"
     ],
     "id": 1,
     "company_name": "RebelMouse"
   }

.. note::

   ``account`` field is Integer and refers to ``Account.id``

Update subscription
--------------------

Update existing subscription.

Endpoint:

.. code::

   PUT /core/paywall/subscriptions/<subscription_id>

Payload example:

.. code::

   {
     "account": 1,
     "name": "RebelMouse",
     "subscription_type": 2,
     "status_active": true,
     "status_count_of_member": 100,
     "email_domain": [
       "@rebelmouse.com"
     ],
     "id": 1,
     "company_name": "RebelMouse"
   }

Response example:

.. code::

   {
     "account": 1,
     "name": "RebelMouse",
     "subscription_type": 2,
     "status_active": true,
     "status_count_of_member": 100,
     "email_domain": [
       "@rebelmouse.com"
     ],
     "id": 1,
     "company_name": "RebelMouse"
   }

Create subscription
-------------------

Create new subscription.

Endpoint:

.. code::

   POST /core/paywall/subscriptions/

Payload example:

.. code::

   {
     "account": 1,
     "company_name": "RebelMouse",
     "email_domain": [
       "@rebelmouse.com"
     ],
     "name": "RebelMouse",
     "status_active": true,
     "subscription_type": 2
   }

Response example:

.. code::

   {
     "account": 1,
     "name": "RebelMouse",
     "subscription_type": 2,
     "status_active": true,
     "company_name": "RebelMouse",
     "email_domain": [
       "@rebelmouse.com"
     ],
     "id": 2
   }


List subscriptions
------------------

Get all available subscriptions.

Endpoint:

.. code::

   GET /core/paywall/subscriptions/

Parameters are:

=========================== ================= ============================================================
Name                        Type              Description
=========================== ================= ============================================================
``limit``                   Integer           Number of items in response (max. 100)
``offset``                  Integer           Skip first N results in response
``date_start``              String            Filter subscriptions where date_start greater than param
``date_expire``             String            Filter subscriptions where date_expire less than param
``subscription_name``       String            Filter by subscription name
=========================== ================= ============================================================

Response example:

.. code::

   {
     "total_count": 1,
     "account": {
       "id": 1
     },
     "subscriptions": [
       {
         "account": 1,
         "name": "RebelMouse",
         "subscription_type": 1,
         "status_active": true,
         "status_count_of_member": 100,
         "email_domain": [
           "@rebelmouse.com"
         ],
         "id": 1,
         "company_name": "RebelMouse"
       }
     ]
   }