# Subscription Status Endpoint

## Overview

The Subscription Status API allows merchants to retrieve comprehensive information about a subscription, including its current status, billing details, dates, and configuration.

### Endpoint

<mark style="color:green;background-color:green;">**GET**</mark> `https://api-stg.directa24.com/v3/subscriptions/`**`{subscription_id}`**

Where `{subscription_id}` is the unique numeric identifier of the subscription you wish to retrieve.

{% openapi src="<https://1770394879-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnTyHI84quh3WRqHk04Z4%2Fuploads%2FewA9Gp9PG1hy92HkxZz1%2Fsubs-get-v2.yml?alt=media&token=22028d22-324f-4349-b883-e56d6feceac1>" path="/v3/subscriptions/{subscription\_id}" method="get" %}
[subs-get-v2.yml](https://1770394879-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnTyHI84quh3WRqHk04Z4%2Fuploads%2FewA9Gp9PG1hy92HkxZz1%2Fsubs-get-v2.yml?alt=media\&token=22028d22-324f-4349-b883-e56d6feceac1)
{% endopenapi %}

### Request Parameters

This endpoint uses only a path parameter to identify the subscription:

<table><thead><tr><th width="141">Parameter</th><th width="134">Type</th><th width="114">Required</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>integer</td><td>Yes</td><td>Unique numeric identifier of the subscription to retrieve.</td></tr></tbody></table>

### Response

#### Success Response

A successful request returns an HTTP 200 status code with the subscription details:

```json
{
  "id": 219,
  "status": "PENDING",
  "start_date": "2020-10-10",
  "end_date": "2020-10-17",
  "creation_date": "2025-02-18T17:18:21.67708163",
  "subscription_plan": "WEEKLY",
  "amount": 10.90,
  "auto_renewal": true,
  "last_modified_date": "2025-02-18T13:49:16"
}
```

#### Response Fields

<table><thead><tr><th width="225">Field</th><th width="137">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>integer</td><td>Unique identifier of the subscription</td></tr><tr><td><code>status</code></td><td>string</td><td>Current status of the subscription (PENDING, ACTIVE, CANCELLED, TERMINATED)</td></tr><tr><td><code>start_date</code></td><td>string</td><td>Date when the subscription started or will start (YYYY-MM-DD)</td></tr><tr><td><code>end_date</code></td><td>string</td><td>Date when the subscription will end if not renewed (YYYY-MM-DD)</td></tr><tr><td><code>creation_date</code></td><td>string</td><td>Timestamp when the subscription was created</td></tr><tr><td><code>subscription_plan</code></td><td>string</td><td>Frequency of the subscription (DAILY, WEEKLY, MONTHLY, ANNUALLY)</td></tr><tr><td><code>amount</code></td><td>number</td><td>Amount charged for each billing cycle</td></tr><tr><td><code>auto_renewal</code></td><td>boolean</td><td>Whether the subscription will automatically renew</td></tr><tr><td><code>last_modified_date</code></td><td>string</td><td>Timestamp when the subscription was last modified</td></tr></tbody></table>

#### Error Responses

The API may return the following errors:

**Subscription Not Found**

Returned when the specified subscription ID does not exist:

```json
{
  "code": 420,
  "description": "Subscription does not exist.",
  "type": "SUBSCRIPTION_NOT_FOUND"
}
```

**Generic Error**&#x20;

Returned when an unexpected error occurs:

```json
{
  "code": 500,
  "description": "Subscription not found id 218 for merchantId 127,885",
  "type": "GENERIC_ERROR"
}
```

### Subscription Statuses

A subscription can have one of the following statuses:

| Status       | Description                                                                          |
| ------------ | ------------------------------------------------------------------------------------ |
| `PENDING`    | Subscription has been created but payment has not been confirmed                     |
| `ACTIVE`     | Subscription is active and billing cycles are in progress.                           |
| `CANCELLED`  | Subscription was cancelled before completion.                                        |
| `TERMINATED` | Subscription was terminated successfully, and all payments were charged accordingly. |

## Webhook Notifications and Payment Flow

When a payment related to a subscription is processed, our system will send notification updates to your configured notification URL. This notification includes a `deposit_id` which is crucial for tracking the payment status.

{% hint style="success" %}
It is important that you integrate the [**Deposit Status Endpoint**](https://docs.pandablue.com/api-documentation/subscriptions-api/broken-reference).
{% endhint %}

### Complete Notification Flow

1. **Payment Processing**: The system processes a payment (initial or recurring)
2. **Webhook Notification**: A notification is sent to your configured URL with a `deposit_id`
3. **Deposit Status Endpoint**: Query <mark style="color:green;background-color:green;">**GET**</mark> `v3/deposits/`**`{deposit_id}`** to get payment details.\
   You can find details of the endpoint [here](https://docs.pandablue.com/api-documentation/deposits-api/endpoints/deposit-status-endpoint).
4. **Subscription Identification**: The deposit response includes the related `subscription_id`
5. **Subscription Status Check**: Query <mark style="color:green;background-color:green;">**GET**</mark> `v3/subscriptions/`**`{subscription_id}`** to verify current status

#### Example Flow

```
Payment processed
    ↓
Notification received with deposit_id=12345
    ↓
GET v3/deposits/12345
    ↓
Response contains subscription_id=219
    ↓
GET v3/subscriptions/219
    ↓
Verify and update subscription records
```

This complete flow ensures that you have full visibility into both payment status and subscription details.