*GET* /dialog/subscribe
=======================

.. note::

    Subscriptions are an opt-in feature. To enable subscriptions, please
    contact sales@laterpay.net.

Returns a HTML-based dialog that starts a checkout process for a subscription.
A user is expected to pay for a subscription with a payment method they have
registered with LaterPay. After the payment is complete, the user gets access to
an ``article_id`` represented by this subscription. Subscriptions renew
automatically according to their ``period``. When a subscription renews, the
user is charged the original price of the subscription and gets access for
another ``period``.


Example URLs:

* https://web.laterpay.net/dialog/subscribe (EU Production)
* https://web.sandbox.laterpaytest.net/dialog/subscribe (EU :ref:`Sandbox <sandbox>`)
* https://web.uselaterpay.com/dialog/subscribe (US Production)
* https://web.sandbox.uselaterpaytest.com/dialog/subscribe (US :ref:`Sandbox <sandbox>`)

Available via HTTPS

Parameters
----------

``article_id`` (required)

    An **unique, service consumer assigned identifier for the current article**.
    This is subsequently used in calls to **/access**. It can be any string
    consisting of lowercase or uppercase ASCII characters, digits, underscore
    and hyphen, the length of which is between 1 and 128 characters.

``sub_id`` (required)

    An **unique, service consumer assigned identifier for the current subscription**.
    This is a subscription specific identifier (There can be different different
    subscriptions for one ``article_id``). It can be any string consisting of
    lowercase or uppercase ASCII characters, digits, underscore and hyphen, the
    length of which is between 1 and 128 characters.

``period`` (required)

    Subscription period in seconds. Minimum value is 3600. Maximum is 31536000.

``pricing`` (required)

    A **list of currencies and prices** consisting of [currency code][price\*100] tuples.
    Example: ``"EUR100,CHF25000,GBP250"``.
    This translates to **1,00EUR**, **250.00CHF** or **2.50GBP**.
    For single sale checkouts, the price is chosen based on the user's payment method's currency.
    **All prices are regarded as including VAT by LaterPay**.

``title`` (required)

    The subscription's title displayed next to the price inside the dialog.
    This must be descriptive of what the user is buying
    (for example "International News Weekly Subscription")


``url`` (required)

    The **URL where the user is sent after they successfully paid for this
    subscription**, i.e. probably the original article itself. This is the url
    associated with purchased article title that users can view on their invoice
    in user backend i.e. this is a canonical url of the subscription.
    ``return_url`` parameter can be used to change where the user is redirected
    after a successful purchase.

``failure_url``

    The **URL where the user is sent when the purchase fails**.

``return_url``

    An **optional URL where the user is sent when the purchase succeeds if it is provided**.
    Use this to add additional private parameters to the successful purchase request,
    e.g. a hash of the user's IP address for verification on your server.

``return_lptoken``

    If this parameter is present and its value is ``1``, an
    :doc:`lptoken </platform/identification/user_tokens>` will be created for the user
    and will be appended as a query parameter to the URL the user will be
    redirected to after successful purchase. See how to receive user tokens
    :ref:`here <receiving_user_tokens>`.

``muid``

    :doc:`Merchant Provided User ID <../../identification/muids>`. If provided then
    LaterPay user's identity will be bound to its value upon user interacting
    with the dialog. Merchant will be able to use a ``muid`` parameter to
    :doc:`/access </platform/access/access>`.

``cp``, ``hmac``, ``ts`` (required)

    :ref:`common_parameters`