# Subscriptions

## API endpoints

{% hint style="success" %}
Authentication: endpoints listed in this page *require* [header authentication](https://docs.powens.com/api-reference/overview/authentication) with a *user token*.
{% endhint %}

## List subscriptions

<mark style="color:blue;">`GET`</mark> `https://{domain}.biapi.pro/2.0/users/{userId}/subscriptions`

#### Path Parameters

| Name                                     | Type            | Description             |
| ---------------------------------------- | --------------- | ----------------------- |
| userId<mark style="color:red;">\*</mark> | Integer or "me" | ID of the related user. |

#### Query Parameters

| Name | Type       | Description                            |
| ---- | ---------- | -------------------------------------- |
| all  | Value-less | Flag to access disabled subscriptions. |

{% tabs %}
{% tab title="200: OK List of subscriptions" %}
Response body: [#subscriptionslist-object](#subscriptionslist-object "mention")
{% endtab %}
{% endtabs %}

{% code title="Filtering route alias:" %}

```
/users/{userId}/connections/{connectionId}/subscriptions
```

{% endcode %}

## Get a subscription

<mark style="color:blue;">`GET`</mark> `https://{domain}.biapi.pro/2.0/users/{userId}/subscriptions/{subscriptionId}`

Get a single subscription by ID.

#### Path Parameters

| Name                                             | Type            | Description             |
| ------------------------------------------------ | --------------- | ----------------------- |
| subscriptionId<mark style="color:red;">\*</mark> | Integer         | ID of the subscription. |
| userId<mark style="color:red;">\*</mark>         | Integer or "me" | ID of the related user. |

{% tabs %}
{% tab title="200: OK Subscription details" %}
Response body: [#subscription-object](#subscription-object "mention")
{% endtab %}
{% endtabs %}

Subscription resources partially support an update operation to handle activation/deactivation:

## Update a subscription

<mark style="color:green;">`POST`</mark> `https://{domain}.biapi.pro/2.0/users/{userId}/subscriptions/{subscriptionId}`

Update a single subscription by ID.

Request body: [#subscriptionupdaterequest-object](#subscriptionupdaterequest-object "mention")

#### Path Parameters

| Name                                             | Type    | Description             |
| ------------------------------------------------ | ------- | ----------------------- |
| subscriptionId<mark style="color:red;">\*</mark> | Integer | ID of the subscription. |
| userId<mark style="color:red;">\*</mark>         | Integer | ID of the related user. |

#### Query Parameters

| Name | Type       | Description                                      |
| ---- | ---------- | ------------------------------------------------ |
| all  | Value-less | Add this flag to access a disabled subscription. |

{% tabs %}
{% tab title="200: OK Subscription updated" %}
Response body: [#subscription-object](#subscription-object "mention")
{% endtab %}
{% endtabs %}

## Life cycle <a href="#disabled-accounts" id="disabled-accounts"></a>

Subscriptions can be in a disabled or enabled state.

{% hint style="warning" %}
For legal compliance, subscriptions are disabled by default. Also, disabling subscription will result in the deletion of subscription child resources (documents).
{% endhint %}

#### Querying

Disabled subscriptions will only appear when passing the `all` parameter:

```
GET /users/{userId}/subscriptions/{id}?all
GET /users/{userId}/connections/{connectionId}/subscriptions/{id}?all
```

#### Enabling

To enable one such subscription, it is necessary to perform a `POST` request on that subscription, with the `all` parameter and `{ "disabled": false }`.

Please note that this action represents the PSU's consent.

## Webhooks <a href="#subscription-webhooks" id="subscription-webhooks"></a>

### Subscription synced <a href="#subscription-synced" id="subscription-synced"></a>

A `SUBSCRIPTION_SYNCED` webhook is emitted during a sync after a subscription was processed, including new documents.

Webhook request: [*Subscription*](#subscription-object) object with the following additional properties:

<table><thead><tr><th width="173.33333333333331">Property</th><th width="249">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>documents</code></td><td>Array of <em>Document</em> objects</td><td>The new documents that were found.</td></tr></tbody></table>

### Subscription found <a href="#subscription-found" id="subscription-found"></a>

A `SUBSCRIPTION_FOUND` webhook is emitted after a **new** subscription was discovered.

Webhook request:

<table><thead><tr><th width="212">Property</th><th width="180.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>Integer</td><td>ID of the bank account.</td></tr><tr><td><code>id_user</code></td><td>Integer</td><td>ID of the related user.</td></tr><tr><td><code>id_connection</code></td><td>Integer</td><td>ID of the related connection.</td></tr></tbody></table>

## Data model

### ***SubscriptionsList*****&#x20;object**

<table><thead><tr><th width="190.33333333333331">Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>subscriptions</code></td><td>Array of <a href="#subscription-object"><em>Subscription</em></a> objects</td><td>List of subscriptions.</td></tr></tbody></table>

### ***Subscription*****&#x20;object**

<table><thead><tr><th width="197">Property</th><th width="173.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>Integer</td><td>ID of the subscription.</td></tr><tr><td><code>id_connection</code></td><td>Integer or null</td><td>ID of the related connection.</td></tr><tr><td><code>id_user</code></td><td>Integer or null</td><td>ID of the related user.</td></tr><tr><td><code>id_source</code></td><td>Integer or null</td><td>ID of the related connection source.</td></tr><tr><td><code>number</code></td><td>String or null</td><td>Subscription number.</td></tr><tr><td><code>label</code></td><td>String</td><td>Label of the subscription.</td></tr><tr><td><code>subscriber</code></td><td>String or null</td><td>Name of the subscriber.</td></tr><tr><td><code>validity</code></td><td>Date or null</td><td>The subscription is valid until this date, if any.</td></tr><tr><td><code>renewdate</code></td><td>Date or null</td><td>Next renew date, is any.</td></tr><tr><td><code>last_update</code></td><td>DateTime or null</td><td>Last successful update of the subscription.</td></tr><tr><td><code>deleted</code></td><td>DateTime or null</td><td>If set, this subscription is not found on the website anymore.</td></tr><tr><td><code>disabled</code></td><td>DateTime or null</td><td>If set, this subscription has been disabled by user and will not be synchronized anymore.</td></tr><tr><td><code>error</code></td><td>String or null</td><td>If the last update has failed, the error code.</td></tr></tbody></table>

**Available expands**

The following parameters can be used for [response properties expansion](https://docs.powens.com/api-reference/overview/api-design#responses-expansion):

<table><thead><tr><th width="178.33333333333331">Property</th><th width="202">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>connection</code></td><td><a href="../../../user-connections/connections#connection-object"><em>Connection</em></a> object</td><td>The connection associated with this subscription.</td></tr></tbody></table>

### *SubscriptionUpdateRequest* object

<table><thead><tr><th width="178.33333333333331">Property</th><th width="114">Type</th><th width="104">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>disabled</code></td><td>Boolean</td><td>No</td><td>Whether the subscription must be disabled or enabled.</td></tr></tbody></table>