> For the complete documentation index, see [llms.txt](https://api.docs.magloft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.docs.magloft.com/portal-api/custom_subscriptions.md).

# 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 %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api.docs.magloft.com/portal-api/custom_subscriptions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.