# 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.onekeypayments.com/v3/subscriptions/`**`{subscription_id}`**

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

{% openapi src="/files/s8qNmPXfCwoB5A9bkJb6" path="/v3/subscriptions/{subscription\_id}" method="get" %}
[okpsubs-get-v2.yml](https://1595349702-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7aIgg5dys0yN8otrASQq%2Fuploads%2Fs6JaHPIhCEIhf6JWfhYE%2Fokpsubs-get-v2.yml?alt=media\&token=7ab890d9-b31c-4409-9f31-c16b3c3d6264)
{% 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**](broken://pages/G4LyvijzUWxyN6nXI2Tn).
{% 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](/api-documentation/deposits-api/endpoints/deposit-status-endpoint.md).
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.


---

# Agent Instructions: 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://apidocs.onekeypayments.com/api-documentation/subscriptions-api/subscription-status-endpoint.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.