# Custom Subscriptions

API for managing Custom Subscription

## List Custom Subscriptions

<mark style="color:blue;">`GET`</mark> `https://www.magloft.com/api/portal/v1/custom_subscriptions/:app_id`

This endpoint **returns** a list of all `custom subscriptions` that belong to the magazine

#### Path Parameters

| Name    | Type   | Description                                     |
| ------- | ------ | ----------------------------------------------- |
| app\_id | String | App ID (Publication) to scope this request for. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "order_id": "sub-12345",
  "source": "custom",
  "user_id": "FF063C1C-C5F3-4749-A7FC-7DCF91B3278F",
  "active": true,
  "start_date": "2018-01-24",
  "end_date": "2018-01-24",
  "created_at": "2018-01-24 10:55:35",
  "reader": {
    "id": 12345,
    "email": "user@magloft.com",
    "custom_data": {
      "gender": "male"
    },
    "confirmed": true
  },
  "status": "updated",
  "password": "pass1234"
}
```

{% endtab %}
{% endtabs %}

## List Custom Subscriptions Page

<mark style="color:blue;">`GET`</mark> `https://www.magloft.com/api/portal/v1/custom_subscriptions/:app_id/page/:page`

This endpoint **returns** a page list of all `custom subscriptions` that belong to the magazine

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| page    | Integer | The page number to list                         |

#### Query Parameters

| Name       | Type    | Description                              |
| ---------- | ------- | ---------------------------------------- |
| per\_page  | Integer | Number of items to show per page         |
| order\_by  | Symbol  | Field to sort results by                 |
| order\_dir | Symbol  | Direction (asc, desc) to sort results by |
| filter     | String  | Text filter to search results by         |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "total": 1,
  "page": 1,
  "records": [
    {
      "id": 1234,
      "order_id": "sub-12345",
      "source": "custom",
      "user_id": "FF063C1C-C5F3-4749-A7FC-7DCF91B3278F",
      "active": true,
      "start_date": "2018-01-24",
      "end_date": "2018-01-24",
      "created_at": "2018-01-24 10:55:35",
      "reader": {
        "id": 12345,
        "email": "user@magloft.com",
        "custom_data": {
          "gender": "male"
        },
        "confirmed": true
      },
      "status": "updated",
      "password": "pass1234"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Get Custom Subscription

<mark style="color:blue;">`GET`</mark> `https://www.magloft.com/api/portal/v1/custom_subscriptions/:app_id/(:email)(:id)`

This endpoint **returns** a specific `custom subscription` by `id`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| email   | String  | Email address of the reader account             |
| id      | Integer | Subscription ID                                 |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "order_id": "sub-12345",
  "source": "custom",
  "user_id": "FF063C1C-C5F3-4749-A7FC-7DCF91B3278F",
  "active": true,
  "start_date": "2018-01-24",
  "end_date": "2018-01-24",
  "created_at": "2018-01-24 10:55:35",
  "reader": {
    "id": 12345,
    "email": "user@magloft.com",
    "custom_data": {
      "gender": "male"
    },
    "confirmed": true
  },
  "status": "updated",
  "password": "pass1234"
}
```

{% endtab %}
{% endtabs %}

## Create Custom Subscription

<mark style="color:green;">`POST`</mark> `https://www.magloft.com/api/portal/v1/custom_subscriptions/:app_id`

This endpoint **creates** a new `custom subscription` and **returns** the saved `custom subscription`

#### Path Parameters

| Name    | Type   | Description                                     |
| ------- | ------ | ----------------------------------------------- |
| app\_id | String | App ID (Publication) to scope this request for. |

#### Request Body

| Name                | Type                       | Description                                                                                                     |
| ------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------- |
| email               | String                     | Email address of the reader account                                                                             |
| password            | String                     | Plain-text password of Reader account shown only when creating a new subscription without specifying a password |
| start\_date         | Grape::ApiDate             | Date from which the subscription should be valid (inclusive)                                                    |
| end\_date           | Grape::ApiDate             | Date until which the subscription should be valid (inclusive)                                                   |
| active              | Virtus::Attribute::Boolean | Boolean indicating whether the subscription is currently active                                                 |
| custom\_data        | Hash                       | Hash containing custom data (string key, string value) of a reader                                              |
| firstname           | String                     | First name of the Custom Subscription's reader                                                                  |
| lastname            | String                     | Last name of the Custom Subscription's reader                                                                   |
| confirmation        | Virtus::Attribute::Boolean | Boolean to indicate whether to send a confirmation email                                                        |
| upsert              | Virtus::Attribute::Boolean | Boolean to indicate whether to update existing custom subscription if the email is registered                   |
| classification\_ids | Array                      |                                                                                                                 |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "order_id": "sub-12345",
  "source": "custom",
  "user_id": "FF063C1C-C5F3-4749-A7FC-7DCF91B3278F",
  "active": true,
  "start_date": "2018-01-24",
  "end_date": "2018-01-24",
  "created_at": "2018-01-24 10:55:35",
  "reader": {
    "id": 12345,
    "email": "user@magloft.com",
    "custom_data": {
      "gender": "male"
    },
    "confirmed": true
  },
  "status": "updated",
  "password": "pass1234"
}
```

{% endtab %}
{% endtabs %}

## Update Custom Subscription

<mark style="color:orange;">`PUT`</mark> `https://www.magloft.com/api/portal/v1/custom_subscriptions/:app_id/:id`

This endpoint **updates** a specific `custom subscription` by `id` and **returns** the updated `custom subscription`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Subscription ID                                 |

#### Request Body

| Name         | Type                       | Description                                                        |
| ------------ | -------------------------- | ------------------------------------------------------------------ |
| start\_date  | Grape::ApiDate             | Date from which the subscription should be valid (inclusive)       |
| end\_date    | Grape::ApiDate             | Date until which the subscription should be valid (inclusive)      |
| active       | Virtus::Attribute::Boolean | Boolean indicating whether the subscription is currently active    |
| custom\_data | Hash                       | Hash containing custom data (string key, string value) of a reader |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "order_id": "sub-12345",
  "source": "custom",
  "user_id": "FF063C1C-C5F3-4749-A7FC-7DCF91B3278F",
  "active": true,
  "start_date": "2018-01-24",
  "end_date": "2018-01-24",
  "created_at": "2018-01-24 10:55:35",
  "reader": {
    "id": 12345,
    "email": "user@magloft.com",
    "custom_data": {
      "gender": "male"
    },
    "confirmed": true
  },
  "status": "updated",
  "password": "pass1234"
}
```

{% endtab %}
{% endtabs %}

## Delete Custom Subscription

<mark style="color:red;">`DELETE`</mark> `https://www.magloft.com/api/portal/v1/custom_subscriptions/:app_id/:id`

This endpoint **deletes** a specific `custom subscription` by `id` and **returns** an `empty response` with status `204`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Subscription ID                                 |

{% tabs %}
{% tab title="200 " %}

```javascript
null
```

{% endtab %}
{% endtabs %}

## Export Custom Subscriptions

<mark style="color:blue;">`GET`</mark> `https://www.magloft.com/api/portal/v1/custom_subscriptions/:app_id/export.csv`

This endpoint **returns** a csv document that contains a spreadsheet of all `custom subscriptions`

#### Path Parameters

| Name    | Type   | Description                                     |
| ------- | ------ | ----------------------------------------------- |
| app\_id | String | App ID (Publication) to scope this request for. |

{% tabs %}
{% tab title="200 " %}

```javascript
null
```

{% endtab %}
{% endtabs %}